Does your code really need comments?

Developers often spend more time reading code than writing it. Cutting that reading time means a productivity boost: more time to innovate, less time deciphering a colleague’s legacy.

It starts with code that’s readable, clear and unambiguous. But what about comments? Code describes what the program does, rarely why it does it. That’s where comments find their real value.

Good comments

• Those that explain why the code exists, not what it does.
• Those that clarify complex parts, like a regular expression.
• Those that flag the critical importance of a line or block.
• Those where an experienced developer guides juniors through tricky code.
• Those tied to legal obligations.

Comments to avoid

• Names and dates of changes: that’s the version control system’s job.
• Decorative frames and rows of useless asterisks.
• TODOs left in the code instead of a tracking tool.
• Excessive comments on already-clear code.
• Stale comments, never updated.
• Code left commented out, a source of confusion.

In short, comments remain useful, but should be used with judgment to genuinely help understanding and maintenance. And to those who think “the code never lies,” I answer with a smile: true… as long as you’re on the right branch.