A Time and Place for Code Comments

I’ve dealt with more than one person who believes all code comments are bad.

The first person I encountered who said that also asked me to explain why a particular algorithm was used instead of another because there were no comments explaining it.

But, one of my primary principles is that you should get the compiler to do as much work as possible when it’s compiling.  This has to do with preferring compile-time errors over run-time errors; but it does have an effect on comments.  The result is that they should be avoided in preference to self-commenting code because the compiler does not check them.

I had the misfortune of working with a fellow once you named his variables starting with “a” and continuing alphabetically, adding a character when he ran out of letters.  His code mike look like this:

    protected Boolean SuspendIfNeeded ( )
        Boolean c = this.a.WaitOne(0, true);
        if (c)
            Boolean d = Interlocked.Read(ref this.b.suspended) != 0;
            if (d)
                /// Suspending…
                if (1 == WaitHandle.WaitAny(new WaitHandle[] { d, this.e }))
                    return true;
                /// …Waking
        return false;

..very painful.

While self-commenting code makes for code that is more maintainable; there are times where the code doesn’t explain some higher-level concepts.  Domain-Driven Design helps to get you in the habit of making domain-specific design artifacts “explicit”, which goes a long way to self-commenting code; but it doesn’t address vital information like why certain algorithmic decisions were made.

This is one area where refactoring tools don’t help.  They will often help deal with XML comments; but inline comments (and comments regarding implementation details don’t belong in XML comments) can get lost unless you’re paying attention–i.e. avoid refactoring by rote.

7 thoughts on “A Time and Place for Code Comments

  1. In general if you can’t write good (expressive) code you can’t write good comments but if you can you don’t need to write so many comments.

    Ergo code with many comments is bad…

    Aaron, I hope you are joking 🙂

    The whole ‘bug #10’ comments with a developers name & date are the ultimate waste of time comments – tracing what & when changed is exactly what any source integrity package should do for you via ‘labelling’.

  2. @Ollie. Yes, often comments are a sign there is an opportunity to refactor, to make the concept the comment describes explicit–like a method or a class. But, there are still times that the code can’t and shouldn’t express certain information.

  3. I actually had a CIO at a company I once worked for tell me that comments were evil, and I was asked to NOT add any more of them. Needless to say I did NOT listen to him and I moved on shortly after that.

    Commenting for the sake of commenting is one thing. But even the most readable code needs comment if the intent is not 100% clear. Or if there are other possible solutions that were NOT chosen.

    Comments are your friend.

  4. It is true that the choice of variable names should render the code self-explanatory but this is not always enough. Comments should explain what is going on elsewhere or event dependencies which are not locally scoped.

    e.g. (I wrote this ten minutes ago)

    _pEntry->AwaitResults(); // Tell DeleteWriteThread profile data is processed
    _pEntry = NULL;

    Locally I’m signalling a barrier but anyone looking at the compilation unit will find it handy to know who I’d expect to be waiting about for the data otherwise it would require a project string search. Not too hard was it?

  5. Hmmm. Comments. They were in 5 years ago and now they are out.

    I have seen people deliberately seek and destroy all comments. I think this is a good thing. We should design our code in a such a way that it “comments itself”. This is what good refactoring and design will do for you.

    The code fragment you have shown is appalling and no amount of commenting will make it better. It needs a good refactoring/redesign.

    For example what is “a” ,”b” and “c”? I thought the practice of naming variables with a single character were left back in the good ol’ C days.

    They could be renamed to variables that make a little more sense. For example

    if (hasReaders) or if (isReadLocked)

    So why say

    //if not read locked

    //if has no readers

    when you can say something like:

    if(!isReadLocked && !hasReaders)

    A coding standard maybe of more help here than comments. Also consider pair programming to detect such code as it is written.

    The problem with comments are:
    1. They are never up-to-date. When the code changes you have to make sure the comments stay up-to-date. This a pain in the rear and often does not happen. So now you are reading and relying on incorrect information.
    2. What happens is someone deletes your comments? If you document the code with itself, this can’t happen because your unit tests will break and your system will stop working. If someone renames all your descriptive methods and variables to the sort of “a”, “dddd()” then running a tool like Checkstyle will help you catch any of these problems before the code is checked into your version control.

    I have to agree that excessive comments are a code smell and hints at design flaws.

Leave a Reply to Ollie Riches Cancel reply

Your email address will not be published. Required fields are marked *