Stop Over-Commenting Code

Most developers know that comments are useful in a codebase. They help to clarify intentions and foster a better understanding between current and future maintainers. But sometimes, commenting code can go too far and actually damage maintainability. Let me explain.

The Problem

Imagine opening up your editor or IDE and loading a new code base. You want to look into a bug or add a new feature. Hence, you need to understand the structure and behavior of a program. There it is: Tons of comments between almost every line of code. Every field of a class has a comment. Every few lines in a method, there is an explanation. Every class has a huge section of comments.

The problem? Most of these comments are not telling you anything useful. They just repeat what is already obvious by looking at the control statements, variable names or program structure. It’s purely redundant. Does it hurt? Yes, it clutters your screen, and the important parts become less obvious to your eyes. Moreover, comments can become outdated when they are not maintained during changes. Then they can actually be misleading.

The Solution

As a rule of thumb, ask yourself two questions before adding a comment:

1. Is this comment saying something relevant that is not obvious from the current structure and naming?
2. Did I already consider restructuring or renaming the code itself to be more expressive and make the comment obsolete?

If you can honestly answer both questions with ‘yes’, then go ahead and write that comment. It is probably useful and adds some value for the reader. Otherwise, please reconsider why you want to add a comment. Avoid doing it just out of a habit or due to some overly dogmatic commenting rule.

Good comments should add value by giving context to a problem and its solution. Focus on explaining non-obvious decisions and giving background information instead of just repeating implementation details that the code itself expresses more clearly and consistently.

What is your experience with code comments? Would you consider over-commenting a real problem, or not at all?

#SoftwareEngineering #CodeComments #Verbosity #Maintainability