Writing meaningful comments and making your team happy.

Perhaps not the most debated topic among developers, but one that is certainly on the list, is how, when and why to put comments in to code.

One side argues that leaving comments and clues is a reasonable courtesy for the poor sap who inherits your code after you are long gone.

The other side claims their code is so beautifully written and self-explanatory that no annotations are required.

In my daily work, there are four places where commentary is possible:

1. In the code itself
2. On source control commits
3. On bug reports or user stories
4. On invoice time records

All of these contexts have different levels of necessary comments, and different purposes (and consequences) tied to those comments.

Inline comments

By far the most common form of inline comment I use is to reference a bug ticket.  Whatever bug tracking or work item system you use, it probably assigns a nice integer to each item.  So when you fix that bug, you can notate the bug that is behind the change.

//24549 send manual refund email if needed
if (manualRefunds.Count > 0)
    SendManualRefundEmail(currentStudentTestEvent, manualRefunds);

These comments make it trivial to find all the changes associated with a bug fix, simply by doing a search for the bug id.

Another rule for inline comments is when, for whatever brilliant reason, a non-intuitive decision is made and implemented in code.  These comments are what make your code ‘senile-proof’.  What I mean by that is that we should just admit we can’t remember everything, and whether for our own sake or for the sake of our team, we need to record what we were thinking when we coded that magic number or unusual sequence.  Other times, we just point out the obvious.

//2011-01-11:DMS - retrieve event to get test method
Model.OpenTestEventSearch openTestEventSearch = TestEventBL.GetOpenTestEventSearch(studentTestEvent.TestEventID)
  .Where(o => o.TestGradeID == studentTestEvent.TestGradeID)
  .FirstOrDefault();

Source Code Commits

Checking code back in to the repository is a historic event.  In doing so, your code (working or not) is forever committed.  Just like any other monument, it’s nice to put a little plaque up to commemorate the event.

In most cases, a commit will follow a bug fix, in which case your commit comments should also include the bug ID and a brief description of the fix.

In other cases, you did something else, such as adding comments (!) or merged a code branch.  In those cases, a brief note about the change will help others on the team know why in the world you committed.

Bug ticket closure

In many (all?) bug tracking systems, when a case is resolved, the user has the opportunity to submit an update to the case.  Again, these notes can be concise, and can reference back to the revision or changeset in source control in which the code changes occurred to clear the case.  The level of detail required depends a lot on the other users of the bug tracking tool.  If end users will get updated upon the case closing, and they want an explanation of the fix, then you should give it to them.  However, if only project managers see it, and they are satisfied with a simple note saying “fixed in DEV branch”, then by all means, save the keystrokes.

Time entries

As a consultant, everything I do is tied to a time entry that ultimately ends up on an invoice to a client.  Therefore, when comments are put on time entries, they need to be ‘client friendly’.  In our case, however, the time entry is associated to a bug or work item, which has already been annotated, so the level of detail required is slightly less on the invoice.

As all developers do, when we inherit someone else’s code, we are thankful for the information left for us by our predecessors.  It’s only reasonable to return the favor for those who come after us.

What are your rules for commenting?  Add your thoughts below.