Use comments sparingly

Developers are encouraged to write comments for the code in detail right from college days. The obvious reason is, it helps in improving readability and making maintenance easier. Apparently, we end up churning more lines of comments for tricky logic, thus resulting in comments sprinkled throughout the code base.

More often, comments are used as deodorants for badly written code.  Comments, as a rule, result in the following problems:

• Encouraging developers to write code which doesn’t communicate its intent.
• Comments are dead documentation. How many of us update the comments when we bring in some code changes? Hence it’s outdated most of the times.
• Along with the code, comments require maintenance.

At times, the “why” part of the code is not obvious looking at the code. If it’s really difficult to communicate the why, then comments can be used.

How then, can one read the code base without comments? Good unit tests can serve as living and updated documentation. Developers should be taught to write clean code and making comments as an exception, not a rule which would push for the developer to write intent revealing code.

Comments are helpful in certain areas:

• Public libraries have comments for each public method or property, which is used to create documentation.
• Explain an hack in your code. A Codebase without hacks is non-existent. This may be due to lot of various reasons, which is not my concern here.

In Clean Code Robert Martin says
“The proper use of comments is to compensate for our failure to express yourself in code. Note that I used the word failure. I meant it. Comments are always failures.”

Developers should strive to reduce such failures. And Comments should be used sparingly.