Are Code Comments That Bad?

There are some (many?) who dislike comments in code, usually to varying degrees. There are some that believe comments have no place in the code. There are others that feel that comments should be used very, very sparingly. I have my own take that isn’t quite as harsh. Personally, I like comments in code, but only comments that meet a specific criteria.

The Case Against Comments

The case against comments in code typically is based on two main arguments. The first is that the comments merely repeat what the code does. That typically implies that the code isn’t written as clearly as it could be, or as expressively as it could be. The second argument is that comments are often not maintained, so at some point, the comments and the code drift apart. It can result in a comment that isn’t just a bit misleading, it is flat-out wrong.

These are perfectly valid arguments, and I agree with their sentiment 100%. Comments that just echo the code don’t add value. It’s clutter that gets in the way. It doesn’t provide any insight. Comments that aren’t maintained are effectively useless. We can say “you have to maintain the comments, not just the code” all we want, but when the pressure to deliver is on, something gets left behind. The code has to work. Since the comments aren’t parsed or compiled, they won’t stop you from shipping. Code that doesn’t work will stop you from shipping. It isn’t hard to see which will be the focus of attention. And no matter how good your intentions, you will never go back to fix up the comments.

So What Are They For?

For me, I want comments that explain “why”. I don’t need a comment to explain the “how” or “what”. I can tell that from the code (or I better be able to tell it from the code. If it isn’t obvious, expect a refactoring in the future). But the “why” can sometimes be hard to encapsulate, and the “why” is less likely to change over time than the “how” or “what”. The rules, logic or implementation may need to be altered, but the why shouldn’t change nearly as much.

But what is an example of “why”? Consider code for financial markets systems: in some cases, a method, class or a whole module of some sort is built to satisfy some regulation. These regulations don’t change much. So if you’ve got something that has to satisfy SEC Rule 605 (more specifically, 17 CFR Part 240 11Ac1-5, from the Securities Exchange Act of 1934), then it would be good to have a brief explanation of the rule as it applies, and perhaps a URL to the actual SEC rule. If this is a class that generates a Rule 605 report, then it could be a block comment at the very top of the class. I can figure out the rest, and if the comment points me to the rule, I can look up the rule and compare it to the code. If you have methods that implement specific sub-paragraphs of the rule, and making the method name incorporate the rule name is impractical, just put the comment at the top of the method. This tells me why. It means I can go to the rule, look up the specific paragraph, and see that the code matches what the rule says it should do.

What I don’t need are comments basically rephrasing the code into English (or worse, rephrasing the code into poorly written and grammatically incorrect English). Those are comments that won’t get maintained, and I am generally inclined to remove them. They don’t add anything to the code, and can actually make it harder to read. They can act as a “fog” that interferes with your vision.

If You Are Going To Write Comments…

As you can see, this shouldn’t require a ton of comments in the code. If or when you write a comment, please use proper punctuation and grammar. While I said “English” specifically above, your comments should be in a language that is appropriate for the team of people who will be working on it. Whatever language is used for the comments, please, write them properly. That means using full, proper sentences. It means correct punctuation. It means correct spelling. When in doubt, keep it simple. If you aren’t Emily Bronte or Mark Twain, then stick to simple sentences. For English writers, that means simple noun-verb sentences. Don’t try to get clever. Skip compound sentences, parentheticals and asides.

But keep the comments to the point. Unless you have some skill with humour in written form, skip it. Just say what needs to be said, write it as simply as possible, and move on. As for what to comment on, it bears repeating: don’t write comments that merely echo the code. Tell me why the code is doing what it does. I can figure out how and what myself.