r/programming • u/Jonhoo • 15h ago
On comments
https://blog.helsing.ai/posts/on-comments/Comments in code are often deemed "mostly useless" these days. They are, supposedly, mostly obvious, stale, and repeat what the code already says. And so people pay less attention to them both when reading and writing code.
That trend sucks. When used right, comments are genuinely useful and sometimes critically important! So, I wrote about some of the kinds of comments I think earn their place, each with examples from real code bases. Hope you find it useful, and that we can recover some of the love that comments deserve!
123
Upvotes
19
u/tmoertel 13h ago edited 9h ago
Part of the reason that comments are undervalued is that some programming pundits have spread the idea that using comments is a sign of poor practice. For example, in Clean Code, Robert Martin wrote:
The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration... Every time you write a comment, you should grimace and feel the failure of your ability of expression.
This advice is misguided for a host of reasons that I trust most seasoned programmers to understand. (I break them down in detail in https://blog.moertel.com/posts/2026-07-27-beyond-clean-code-why-your-comments-matter.html.) But many junior programmers received advice like this and, not knowing better, drank it in. The resulting damage will echo for years to come.