No Comment

Comments in code are wonderful. They can clarify a bit of code that is otherwise quite obfuscated, allowing the reader to figure out what is happening. They can be used to generate pop-up help in code editors to give programmers help how to use a function or method. They can be used to indicate the history of a method or function and maybe some pitfalls to watch out for.

Consequently project managers and company policies often dictate that every function, method, parameter, property or class be commented by the programmers.

But this is not always a good thing. Coding is much more fun than writing comments about it; So the comments are often given much less attention than they deserve.

Instead you wind up with comments that make wish you had no comments at all.

The inappropriate comment

This is what happens when the comment is first put in place at the time the subject being commented is defined.

But, while the code evolves, the original comment rarely changes in concert with the code. After all the comment, by its very nature, is not a functional part of the program and is thus not tested for validity in normal unit testing. Sometimes the changes are quite subtle, sometimes they are quite drastic.

So as the life cycle of a project progresses, the comments become more and more divorced from reality.

With a lot of code exhibiting the divergence of comment with the code, the reader soon learns to never trust the comment, rendering it obsolete.

The ridiculous comment

Someone on the team, usually the one who cannot really program, will take the thou shalt comment all code commandment very much to heart and pepper the code with more lines of comment than actual code.

// i is counter
// iterate over all elements in array
for (int i = 0; i < array.length; i++) {
    // assign x to the ith element of the array
    var x = array[i];

    // test whether x is less than 10 and greater than 2
    if (x < 10 && x > 2) {
        // x is less than 10 and greater than 2
        ...
    }
}

Here the author is commenting parts of the code that really have no need for a comment.

Any programmer should be able to read the above code and figure what is going on here without having to read the comments:

for (int i = 0; i < array.length; i++) {
    var x = array[i];

    if (x < 10 && x > 2) {
        ...
    }
}

In this instance the comments wind up being annoying, cluttering the code needlessly. Here the reader learns the lesson that the comments are not worth reading.

The meaningless comment

This is slightly different to the ridiculous comment.

The meaningless comment typically raises its head where some compiler option forces every function and parameter to have a comment.

The author, focused on implementing the code, will enter as little as possible to get past the compiler. This leaves a comment without any real or meaningful information:

/// <summary>
/// Finalises the script
/// </summary>
/// <param name="response">The WebGateResponse</param>
private void FinaliseScript(WebGateResponse response)
{

Here the description Finalises the script does not really tell us anything more than the method name FinaliseScript. And telling us that response is The WebGateResponse, really does not tell us anything either.

A reader encountering comments of this calibre soon learns that the comments provide no information and are best ignored.

If you don't have anything nice to say ...

So what is the solution? Comments are useful, but as we have just seen, can be confusing and downright misleading.

You might remember your mother saying:

“If you don't have anything nice to say, don't say anything at all”

This really also applies to comments in code, but the quote may need to be modified a little:

“If you don't have anything meaningful and appropriate to say, don't say anything at all”

Instead of insisting that comments are entered up front, it might be prudent for managers to only check for comments at the later stages of the life cycle, when the design has had some time to settle.

Comments should be part of the code review

By making the comments part of the code review, you can avoid several of the pitfalls mentioned above.

Comments are appropriate

As you are already reviewing the code, it should be not much extra burden to ensure that comments, if present, still reflect what the code is doing.

Check for meaning

Again, as you are already reviewing the code, it should be simple to check that any “required” comments contain more than just the stubs to get past the compiler.

Weed out ridiculous comments

If the code so blatantly obvious that it needs no comments, remove the comments now.

Cull dead code

Sometimes programmers will comment out the old version of a function. While this might be instructive to show how something was done in the past, it really does not help in reading the current code.

So make sure that the old code is indeed still of any relevance. For, if it is not, it merely becomes detritus that requires needless scrolling.

Following these simple steps should ensure that you have properly commented code.