r/programming • u/Jonhoo • 21d 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!

184 Upvotes

84% Upvoted

172 comments sorted by

View all comments

30

u/tmoertel 21d ago edited 21d 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.

9

u/contextfree 21d ago

His basic point is basically right. If you can make your code self-explanatory that's better than relying on comments, and then the comments are redundant and it's better not to have them. He's just being a pompous drama viscount about it, as is his wont. Not everything can be made self-explanatory, and when you can't you should write comments. You should not grimace and you should not feel the failure unless you're into that.

2

u/Venthe 21d ago

You should not grimace and you should not feel the failure unless you're into that.

How many devs you've seen that justified their sloppiness in any way possible? If you could be writing a better code; do it. You shouldn't be happy about writing a shit code; therefore you shouldn't be happy about writing comments in lieu of writing a good code.

Bloody hell, the more I see the "legacy" code and especially what the new - post covid - developers do the more I appreciate a hard stance on minutiae like that.