Whether or not to comment on code is one of the great developer debates, and today we’re wading in.

I don’t know how many times I’ve heard “good code is self-documenting” but at this point it makes me want to shout. Partially because it’s not true, but also because it’s true enough to mean that developers have been saying it in some form for 30 years now.

Okay, let’s back up. Is good code self-documenting? Sort of, sometimes, not really. Here’s a rule of thumb: perfect code is comprehensible without comments, but you should never assume your code is perfect. Stay humble, and you could just prevent major headaches for whoever has to maintain the codebase after you. With that out of the way, I’m going to try to break down when you should comment and when you shouldn’t.

Why Are You Doing That?

If commenting has to explain how something works, that can definitely be a type of code smell. If commenting explains why something works like it does, that’s generally legitimate. Maybe a previous developer drove themselves mad trying to do the obvious thing and failing, so they came up with a workaround. /*I know what you’re thinking, but trying to change globalGodVariableFrom1998 breaks everything, so I used this to get around it.*/

We often find ourselves deviating from the normal way a particular operation is done, because it suits our particular codebase better. In those cases, it’s often good to let people know why, so they don’t end up refactoring your fix and breaking everything, wasting their time.

When Your Code is (Necessarily) Complex

The common wisdom is that if your code needs comments, it’s too complicated: just name your functions better. I mean, yes please, name your functions well, but never assume that you’ve got it absolutely perfect. Especially in large, complex codebases, there can often be overlap in functions, or a cluster of functions working together on the same thing; an accountancy app only has so many variations of paymentReceived before the developer has to get creative.

Commenting on code that should be simple is code smell, but not all code can or should be simple. Some ideas are really hard to express in ways that are both short and clear, and it’s probably better for others and your future self to leave some comments.

When You Run Into Bad Code

I know it will shock some of you, but bad developers exist. Bad developers, contributing to my codebase? It’s more likely than you think. It might even be you. But hey, we’ve all run into some bizarre global variable or some nonsensical function that’s stuck in infinite callback hell, but trying to change it just breaks everything and you can’t fix it for the life of you: if it’s not commented and you manage to figure out what it’s doing, leave a note.

A perfect comment: helpful, informative, to the point

Ideally you refactor and fix the whole thing, but you don’t always have the time or the skill and in that case, make life easier for the next person to come along.

When Something Is Important

The more crucial a particular piece of code is in stopping everything from breaking, the more likely it is to need comments. Even if the code is perfect, even if the code is relatively simple, if this one function breaking will send the house of cards tumbling down then there should probably be something there to help clarify exactly what’s going on.

One thing a lot of developers seem to miss is that the person who comes after you might not be on your level, and things that seem obvious to you can trip them up. I don’t recommend commenting absolutely everything to protect against this, but if it’s the single jenga piece holding the tower up then you want to be extremely sure that they’re not going to pull it by accident and waste a bunch of time figuring it out.

When Not To Comment

First and foremost, to be rude. We’ve all seen it, and it can be devastating to morale: /*this workaround is because of JEFF, good going idiot*/. It doesn’t matter if you’ve ticked every other box, being rude adds nothing and risks making life a lot harder.

Also, I don’t advise comments on each line: if you’re doing more than one comment per block, it’s probably overkill. Heck a comment on every block is probably overkill. My general rule is maximum of one comment per function.

The other big one is to not comment when something is obvious. The important caveat here is that obvious to you is not the same as obvious—assume a junior developer is going to be working with it, and in the absolute worst-case scenario you’ve added a comment that makes a senior developer roll their eyes. Any good IDE can fold in comment blocks in a click or two, and worries about polluting the codebase are often overstated.

It’s definitely possible to over-comment (if somebody can’t figure out that Math.random() pulls up a random number then they’re probably in the wrong workplace) but more developers err heavily in the side of under-commenting and it can be a serious problem; the old “good code is self-documenting” has led to more chaos in development teams than almost any other tech aphorism.

I guess what I’m trying to say is this: be generous. Be kind to those who came before and those who come after. Not everybody is you, so you need to meet them on their level, and the format that often takes is commenting code. The idea that good code is self-documenting is a nice idea, but things are often more complicated than that in practice—refactoring an entire codebase often isn’t an option, and you’ve got to go forward with the tools you’re given.

Comments aren’t always necessary, but there’s no need to disdain them and ignore their use entirely; a screwdriver isn’t good for driving in nails, but if you throw it out because it’s not useful for every single job then you’re going to be in trouble when you run into a screw.

If you’re looking for a great developer job, CodeClouds is one of the best companies in Kolkata to work for! Of course, if you’re just looking for more great reads, why not read this beginner’s guide to Docker?