Comments I Hate

In programming, we are constantly told to ensure we write comments, and this is very good advice. One of the things that is often overlooked in this advice, however, is what kind of comments we shouldn’t make. Having written code for some 30+ years at this point, I have run into 3 specific situations where a comment is not a benefit, and is often simply noise and a negative to everyone involved.

Obvious#

The first kind is the one that people often think of. The one that looks something like this:

/* Increment x by 1 */
x += 1;

You’ve seen them littering various code bases, written by people who took the “document your code” a bit too literally. The funny thing, though, is that there is a time where commenting on this simple little expression might be useful:

/* Convert from zero-based to one-based coordinates */
x += 1;

Now you know why that little line of code existed (and yes, I know I’m missing the bounds checking, but then, this is C code after all). The thing with comments is they shouldn’t tell the reader what you are doing—that’s something that your variable name choices and logical structure should demonstrate—instead they are there to explain why you are doing something.

If, for example, you write some code which you think is particularly clever, that’s a sure indication that it needs comments, and maybe a whole paragraph or two of explanation of why you’re doing what you’re doing. Or just don’t be clever.

You Have SCM#

The next type of comment that is somewhat exhausting is one that was more forgivable when I first started. You see it and it looks something like this:

# CTR [12/3/18]: Added to support new frobnification
def frobnifier(foo, bar, baz=None):
    ...

While I’m old enough to remember a time period where we didn’t have robust version control systems (I see you RCS haunting my memory), that time is long ago. Today, we have multiple good version control systems, so keep your change log in the VCS and let people look there if they want to know why the code was written or when. As they say, that’s what git blame is for.

Inaccurate#

The final one is the worst of all. While the others can be a bit forgiven, sometimes you see a comment that is simply and indisputably wrong. Not just off, but misleading in a way that costs you substantial time. I remember trying to debug some code, nearly 30 years ago, and kept getting to a point where I was sure it was in a certain section. I kept looking at it, but the comment was clear and well written, and from the comment everything looked great.

Surprise!

When I finally just started digging into the debugger and single-stepping through things, I discovered that, in fact, the comment was not just inaccurate, it was misleading and the code didn’t actually do what it said it did. Once that was done, I was able to fix the bug and move on, but I lost several hours of my life to that comment, and I’ll never forget (or forgive) it.