How do you comment your code?

By Steve Endow

It's one of those overused sayings, like "eat healthy" or "brush and floss regularly", but it's for developers:

"Comment your code."

It even applies to consultants who only occasionally dabble in SQL.  "Comment your code."

Okay, so we've all heard it before, but what does it mean to "comment your code"?

My philosophy around code comments is that they should try to answer the following questions:

1. When
2. By Whom
3. For Whom
4. What
5. Why

For example:

//4/11/2016: S. Endow:  Per Sally Smith, modify the freight calculation routine to include evaluation of dim weight to determine best shipping vendor to reduce shipping fee. Prior calculation didn't consider dim weight, resulting in oversize package fees for new Titan Series products when shipped through certain carriers.

When:  April 11, 2016

By Whom:  Steve Endow

For Whom:  Sally Smith

What:  Changed freight calculation routine

Why:  Old routine didn't consider new product line



So why do I try to cover these 5 points in comments?  After developing Dynamics GP integrations and customizations for the last 10+ years, I've realized that those were the questions that I needed to answer when trying to figure out why an application was behaving a certain way.

3 years after I deploy my code, I simply can't remember why specific changes were made.  After several years, I can look at the code and have no recollection even writing it.  I used to write comments that would answer When, By Whom, and What.  Over time, I learned that For Whom was very important:  "So where did that change come from? Who requested it?".  If I didn't comment that information, the client would think I made that change by my own accord, which is silly, but without a comment, I was unable to tell them who requested the change.

So then I started adding For Whom.  But then I would find comments that would tell me what I changed, and for whom I made the change, but we had no recollection of why we made the change.

Why did we change the overtime calculation to exclude those pay codes?  Why is the code handling company A different from company B?

The Why became one of the most important questions that remained unanswered in my comments.

I still have a hard time remembering to add the Why all of the time.  At the time you make the change, it seems so obvious, so it's very easy to forget to document the Why.  But I've found that "Why" is often the most crucial part of a comment when you have to decipher your code years later.

Given my criteria for code comments, after writing thousands of comment lines, I finally got sick of typing the same thing over and over again:  the date and my name.  So I installed a simple "paste" macro tool that will automatically type out some text when I press a keyboard shortcut.

So I've programmed my Win+C keyboard combination to output my basic comment start:  //4/11/2016: S. Endow:


It seems trivial, but it all adds up, and by using the macro, it makes it that much easier for me to add comments, encouraging me to do so.

So I then had a pretty good practice of adding meaningful, useful, and valuable comments throughout my code.  But what about release notes?  In a Visual Studio solution with thousands of lines of code in numerous classes in multiple projects, where do you put your main, summary, release notes?

At one point, I would put them at the top of my Form Main code.  But that didn't work for console apps.  So for console apps, I put them at the top of Program.cs.  But then what about class libraries that have neither a Main Form nor a Program.cs?  This approach starts to break down quickly.

So I did some searching to see if anyone had a best practice.  After reading a few suggestions on StackOverflow, I settled on Documentation.cs.


Every time I create a solution, I create a Documentation.cs class that just contains my release notes and related release comments. At first this felt pretty strange.  An empty class with only comments?  Why not a text file or some other type of file?  Well, because a cs file is easy and will always be picked up by source code control.

If I have multiple projects in my solution, my Documentation.cs will be in my Library project.

After using Documentation.cs for a few months, I now love it.  It's very simple and easy and is just something I do without thinking about it.  And I know exactly where to look for release comments and functionality changes.

When I put comments in Documentation.cs, I have no reservations about being verbose.  Lay it all down with as much context and background and detail as possible, because 1, 2, or 3 years later, you'll need every clue you can get to troubleshoot or refactor.

This is an example of the comments I put in my Documentation.cs file.


I start with the date, then list the version of that release, then list every change that I made, sometimes referencing the specific class and method that was changed.

Every time I write code, and every time I comment my code, I'm constantly thinking, "What would an experienced developer think if she saw my code?" The code I write is just as much my deliverable as my deployment guide or user documentation.  It's the ultimate end product.  Except that very few people other than me actually look at it.

But when you get a call from a customer who suddenly gets an error with the solution that you deployed four years ago, you'll be the one who is scrutinizing that code in far more detail than any customer would.  And you'll appreciate your detailed code comments.

http://www.precipioservices.com