To comment or not to comment, that is the question. Whenever a programmer writes a comment, she is writing for another human being, not a compiler. She is writing the comment in hopes of helping either her future self and/or fellow developers gain a better understanding of the code. Although it is possible to write a comment that clearly explains the code, it is often an indication that there is a deeper problem. Here are some reasons why programmers should refrain from commenting:
Complicated or Unreadable Code
If you need to write comments in order to explain your code, then this is a sign that the code itself needs to be refactored. A simple solution is far better than convoluted code explained with comments. Even giving descriptive and honest names to functions is better than writing a comment. Programmers might feel the pressure of the ticking clock and believe that they cannot spend time writing clean code; however, if writing messy code becomes a habit, then technical debt accumulates, and, in the end, the company spends even more time fixing problems.
You might decide you no longer need certain lines of code, but you do not want to remove them in case if you need them again. This is why we have version control. It is best to just delete obsolete functions, variables, or classes than to leave them forgotten. If you need the code again, you can simply find it in the version control.
If you’re tempted to create bookmarks to help you find specific lines of code, then that is most likely a code smell indicating that you either have bad names or there is some organizational issues. Instead of using comments as bookmarks, you should use your IDE to quickly find names of variables, files, functions, and etc.
This is not to say that you should avoid commenting at all cost. However, I whole-heatedly agree with Robert C. Martin’s sentiment concerning comments in Clean Code:
“Every time you write a comment, you should grimace and feel the failure of your ability of expression.”
Before writing a comment, ask yourself why, and then try to fix the problem instead of putting on a band-aid. If this is not at all possible, well, then, remember to “grimace”.