Comments on comments

Comments on Comments

I have been around long enough to realize that there are as many sets of commenting guidelines as there are organizations which produce software and that the rules will change over time.  Here are my personal thoughts and opinions on this subject mostly from a maintainers perspective.

The most important thing is to give information which will quickly let a maintainer know what the code/method/subroutine/module is supposed to do.

The simplest type of documentation is to use symbol names ( variables, subroutines, modules etc ) which convey an idea of what the item is used for.  I once thought this was not particularly important until I was asked to make a few changes to a program where the comments and code were written by a French programmer.   I also once had a very inventive colleague who chose names and used comments which made the code read something like a novel.  The code was very memorable but very difficult to debug or make rational changes to.

A exception to the above rule is the use of variables named I, J, K etc as counter or index variables which are only used as a counter or index into a data structure and no meaning at all outside the loop.

It is not a good thing to describe in great detail what the code is doing.  This is typically not very helpful and when the code is changed for any reason,  the comments will need to be updated also thus doubling the required effort ( it might be better to just remove the offending comments ).  The worst thing would be to update the code but not the comments because a poor maintainer will not know if the comments are correct or the code.

The simplest type of comment is appended to a line of code. This at least  has the virtue of being removed if the code line is removed.

One of the most useless comments looks like the following:

     A = B;  // assign B to A

A better comment would be to describe why the assignment is needed e.g.

    // Preserve parameter B for later restoration

If for some reason you feel compelled to place a comment for every line of code please do it a the end of the line so that a maintainer does not have to skip every other line while trying to figure out what the code is actually doing.
   getParams(args);         // put command line parameters into the global space

For code blocks, a simple one or two line comment just ahead of or a the end of a block can be very helpful.

  // Initialize all framework global data areas

    getParams(args);

    getProperties();

    getEnvVariables();

 // end of initialization

The above is a very simplistic example and the comments may be not be needed but:

• They should never need to be changed ( i.e. no maintenance required )
• They very effectively mark where any initialization changes should be made

For larger blocks of code e.g. modules and subroutines it can be effective to create off a block of comments before coding begins which at least describe the code blocks in the order in which they appear with TBD (to be done) in the places where code is supposed to go.  This serves as a guide during code implementation and encourages simple changes to maintain accuracy.  The TBD or some thing similar can be quickly recognized as a place where code is incomplete.

Many IDEs such as eclipse support comment generation for various type of code blocks -- use them.

Comments should be brief and describe at least what is being done and why not how it is being done.
All rules have exceptions including this one.

An exception to the brief rule is for library routines written in script type languages.  In this situation, the comments near the front of the code also serve as the user documentation and of necessity should contain enough information to allow proper use of the code.

An exception to the don't explain how rule should be made for blocks of very dense or intricate logic.  In these cases the comments should explain how the code accomplishes the stated purpose of the code.

Another type of comment I have seen many times reads something like:
// Fixes bug 234
Unless the the bug report data base is readily available, the only purpose this serves is to raise a flag if there are several such comments in a given block of code.  This situation should cause serious consideration to be given to a plan to re-implement the affected functionality.  I stated it the way I did because it may not be a problem with the flagged code but that the calling code is using the this code incorrectly or with incorrect expectations.

To re-iterate, the most important thing is to give information which will quickly let a maintainer know what the code/method/subroutine/module is supposed to do.