Some people still think adding comments to their code is a good thing. It’s not. Here is why.
No Information
Most comments add no information to the file what so ever. If I write // initializing i with 0 in front of int i = 0; then this does not provide any information to anyone who understands the basics of programming. And I don’t want anyone working on my code who is incapable of programming. So the comment does not provide any information to the reader what so ever.
Once you start paying attention to comments you encounter, you will find that almost all comments fall in that category: they don’t add any information that is not there already in the source code. So why would you add them? I also don’t add drawings or poems to my source code. While they might please someone’s sense of aesthetics, they don’t add anything.
Wrong Information
Worse than useless comments are comments that are just plain wrong. If a reader of the file actually pays attention to the comment, he will be misled. This can result in bugs and increased maintenance costs.
Also note that irrelevant comments have the potential to become wrong very quickly when code is changed. I’ve seen so many instances of things like // initializing i with 0 followed by int i = 1;. Engineers work on code. And they tend to ignore comments.
Vertical Screen Space
For me vertical screen space is a very important resource. For me it’s easy to follow code that fits my screen. The second I have to start scrolling up and down my screen, it’s significantly harder to follow the code. And useless comments take up vertical screen space. So they always reduce readability.
Two Languages
In Swiss cinemas sometimes American movies are shown with original audio and subtitles in German and French language. For me this is a tiresome experience. While I understand most of the spoken words I am reading the subtitles in German. And often the subtitles vary a bit from the spoken words, e.g. because they have to fit on the screen.
Also the French subtitles are shown directly below the German ones. So after I am done with reading the German one my brain automatically starts reading the next line. And starts processing the same information again in yet another language.
For me reading code that’s riddled with comments is pretty much the same experience. It’s very tiresome for my brain to constantly switch back and forth between Java and plain English.
Rarely Justified
As outlined above most comments are either useless or harmful. There are very few exceptions from this. Even comments that add information are often not the best solution to a problem. E.g. a comment explaining the purpose of a variable can be avoided by choosing a better variable name. The same often applies for comments explaining the behavior of a method.
Fix
If you are tempted to write a comment that does not add non-trivial value, just skip it. If you are reading code and find trivial or wrong comments, just delete them. You will improve the readability of the code immediately.
Conclusion
- Most comments do not add any value.
- Comments are distracting clutter.
- Comments take up screen space.
- Some comments are outdated, misleading, and harmful.
- Often comments can be avoided easily by improving code quality.
- Avoid comments.
- Delete useless and harmful comments.