Comments

Rec.: Comments should be easy to update and maintain.

Rec.: In C++ and Java, use // for tactical (one line) comments, as they are easier to maintain.

Rec.: Use an automatic documentation tool (e.g. javadoc or ccdoc) if possible.

Comments and documentation are essential to source code and must be included whenever appropriate. However, it is a common mistake to think that a comment is always good and that it is better to have more rather than less. This is not so.

First, it takes time just to read a comment. If a comment is redundant or states the obvious then it is actually worse than useless, as the time spent to read it is completely lost.

Also, comments must be properly maintained. If a comment contraddicts the code, then someone will have to figure out whether to code or the comment is wrong. Perhaps, both are wrong. Again, it is not difficult to imagine some better way to spend one's time.

Fortunately, there is much less need for comments if the code is well structured and the identifier names are choosen carefully.

Good comments are clear and short, and describe the intent of the code that follows. They may provide enough information to completely understand the code, or point to the required documentation if necessary. This is sometimes called a strategic comment. On the other side, a tactical comment is an extremely short description associated to very few lines of code, and possibly just one line, that explains what the code does. Tactical comments tend to clutter the code and make it less readable, so they must be used with care and only when necessary. In general, the code should be clear enough to explain itself (as we'll see, this is in part achieved by choosing good identifier names).

Consider the difference between this:

    int gcd( int a, int b )
    {
        while( b != 0 ) { // Loop until b is zero
            int old_b = b; // Save value of b

            b = a % b; // Get remainder
            a = old_b; // Restore the value of b
        }

        return a; // Return result
    }

and this:

    /* Computes the Greatest Common Divisor of a and b using Euclid's algorithm */
    int gcd( int a, int b )
    {
        while( b != 0 ) {       
            int old_b = b;

            b = a % b;
            a = old_b;
        }

        return a;
    }

The second version is identical to the first except that all the useless tactical comments have been removed and the intent of the function is clearly stated with a short strategic comment: this version is much more readable and does not require you to rediscover Euclide's algorithm by reverse engineering the code.

Note however that the comment is associated to an implementation, so it does explain the method used to compute the result. For a declaration it is better to omit the unnecessary information and include only a description of the function:

    /* Returns the Greatest Common Divisor of a and b */
    int gcd( int a, int b );

Since the declaration is usually placed far from the implementation, this helps keeping the comment in sync with the actual implementation, which with time could have been reworked to use a different algorithm.

Better still, tools like javadoc (for Java) or ccdoc (for C++) make it possible to automatically create documentation with very little effort on the programmer side.

Do not use /* */ comments to disable sections of code, as probably these comments cannot be nested. In C++ use #if 0 and #endif instead. Best of all, if some code must be permanently removed then just remove it altogether rather than leaving it to confuse the rest of the program. If necessary, older version can still be retrieved using a version control program.

Rec.: Comments should be easy to update and maintain.

Avoid forms like:

    /*******************************************************
     *                                                     *
     * This is a difficult to maintain comment...          *
     *                                                     *
     *******************************************************/

Adding text to the above is long and tedious, and the comment is more likely to go out of date soon.

Rec.: In C++ and Java, use // for tactical (one line) comments, as they are easier to maintain.

Rec.: Use an automatic documentation tool (e.g. javadoc or ccdoc) if possible.