Comments Are A Smell

I’ve talked about comments in the past. Comments are a code smell, right? Maybe, or maybe not. It depends. Like so many things in the software world, a recommendation phrased as a comparison has been turned into a binary flag.

Why that happens is understandable. Binary is easy. True/False. 1/0. So easy even a computer can understand it. It reduces cognitive load. On the other hand, comparisons and value statements are hard. There’s more cognitive load. So instead of Working software over comprehensive documentation, people say don’t bother to write documentation. And from comments often are used as a deodorant we get Code never lies, comments sometimes do and conventional wisdom saying comments are bad. It is known.

The thing is, Just like in Game Of Thrones, just because it is known, it isn’t necessarily true. Taking these value statements as binaries leads to the bigger problem of the things we know that just ain’t so.

Are comments a code smell? Yes. That just means they might be a bad thing. Are they a bad thing? They might be. It depends. Comments that just duplicate the code are a smell because the code and the comments don’t always change together. Which means you end up with stale comments. And those are a bad thing.

Comments that describe the code because the code is hard to understand are also a code smell. This is where the phrase comments are sweet smelling comes from. The comment is there because it smells good. It’s definitely a code smell. It makes the code easier to understand. It helps the next person who must look at the code.

But just like regular deodorant, it’s masking another smell. One that isn’t so good. The fact that the code in question can’t be easily understood is also a smell. It’s just been masked. So even though the comment is a good smell, it’s still an indication of a problem that ought to be addressed.

Other times, comments are there to explain why. They’re there to let future developers know some bit of arcane business knowledge or external factor that means the code needs to be this way. Or they might be there to explain what conditions might arise that would cause the code to be sub-optimal, or maybe even be invalidated. Or what needs to happen so that the code could be removed entirely. All of those are smells. Things that are right for now, but might need to be looked at again later.

So yes, comments are a code smell. It’s a sign that you need to look at the code and the comment and think about why they’re there and what should be done about it and when.

But, just like all the other code smells, it’s not an absolute. It doesn’t mean Thou shalt not write comments. It means that you need to think before you type.