Why do we need code comments? I would not be surprised if your first answer is, “We don’t.”
I get it. Senior developer after senior developer has taught us that “comments are bad.” And we cheerfully nod our heads, saying, “I am smarter for not using them.” We grin smugly when we see one of our juniors make the “mistake” of using comments in their code.
But as much as we sometimes abuse them, we still need comments.
I know comments don’t affect the code’s behavior. I understand how they can get stale and stop making sense. I am all for writing clean code, and I do my best to ensure my variables, methods, and class names describe their intent as accurately as possible. If I see dead code lying around in the comments for a while, I delete it.
But here is the bottom line: we need code comments because there are some things they do better than plain code. Here’s why. Many languages have the ability to turn specific comments into rendered documentation. This gives you a quick and easy way to give a clean set of docs to your users or other developers. The comments are also near to the code, so you can update them as needed.
The first place where code comments shine is in experimentation. Picture a time when you were trying to figure out one of the more complex bits of your application. Perhaps you were dealing with a tough query with multiple subqueries. Or you may have been trying to understand a multi-loop algorithm with many conditions.
It’s not a bug. It’s an undocumented feature!
For starters, there are really two different types of code comments. I call them documentation comments and clarification comments.
Documentation comments are intended for anyone who is likely to consume your source code, but not likely to read through it. If you are building a library or framework that other developers will use, you need some form of API documentation. The further removed from the source code your API documentation is, the more likely it is to become outdated or inaccurate over time. A good strategy to mitigate this is to embed the documentation directly into the code and then use a tool to extract it.
The downside of these kinds of comments is that they can make your code very “noisy” and harder to read for anyone who is actively involved in maintaining it. The good news is that most code editors support “code folding” which allows us to collapse the comments so we can focus on the code.
Clarification comments are intended for anyone (including your future self) who may need to maintain, refactor, or extend your code. Often, a clarification comment is a code smell. It tells you that your code is too complex. You should strive to remove clarification comments and simplify the code instead because, “good code is self-documenting.” Don’t get me wrong, there are times — especially when you are slogging through a crushing workload — where injecting a bit of humor can be good for the soul. But when you write a funny comment to make up for bad code, it actually makes people less likely to refactor and fix the code later. Do you really want to be the one responsible for robbing all future coders of the joy of reading that clever little rhyme? Most coders would chuckle and move on, ignoring the code smell. There are also times when you come across a comment that is redundant. If the code is already simple and obvious, there’s no need to add a comment.These things may seem funny or may help release a bit of frustration in the moment, but when they make it into production code they end up making the coder who wrote them and their employer look unprofessional and bitter.