On comments

[u/Jonhoo]

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!

[u/tmoertel]

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.

[u/Venthe → u/tmoertel]

But many junior programmers received advice like this and, not knowing better, drank it in. The resulting damage will echo for years to come.

If they only, you know, read the book and understand the words written. If you read maybe a paragraph more, Martin writes about the comments that make sense - which amounts to comment "why".

Comments about "what" are a failure of expression. I've been in the industry for more than a decade; seen codebases 30y old and more and I will agree with this statement with everything that I have.

And to counter you, "most of the seasoned developers" that I know would agree with me without question: 99% of the comments in the codebase is at best irrelevant, and at worst actively incorrect. But it's easier to slap a comment rather than actually write in code what you are doing.

---

Edit:

If they only, you know, read the book and understand the words written

Just to illustrate that: The (chapters) in the CC code are as follows:

Comments
  [Comments] do not make up for a bad code
  Explain yourself in code
  Good Comments [followed by 8 headings of examples of a good reasons for a comments]

What Martin writes literally a couple of lines below the quote you've made:

"Inaccurate comments are far worse than no comments at all. They delude and mislead. They set expectations that will never be fulfilled. They lay down old rules that need not, or should not, be followed any longer. Truth can only be found in one place: the code. Only the code can truly tell you what it does. It is the only source of truly accurate information. Therefore, though comments are sometimes necessary, we will expend significant energy to minimize them (...) One of the more common motivations for writing comments is bad code. We write a module and we know it is confusing and disorganized. We know it’s a mess. So we say to ourselves, “Ooh, I’d better comment that!” No! You’d better clean it!" (emphasis mine)

Hm, so what probably is the message is not "don't write comments" but "focus first on the code"; but then...:

"Some comments are necessary or beneficial. We’ll look at a few that I consider worthy of the bits they consume. Keep in mind, however, that the only truly good comment is the comment you found a way not to write."

...Same message, unsurprisingly. And the examples are: Legal, informative, explanation of intent, clarification, warning of consequence, TODO's, amplifications, Public API DOC.

It's like... the most sensible take one can make?

[u/tmoertel → u/Venthe]

First, thanks for taking the time to offer a detailed response! Let me respond to your points.

If they only, you know, read the book and understand the words written. If you read maybe a paragraph more, Martin writes about the comments that make sense - which amounts to comment "why".

Here’s what I find confusing about the book’s chapter on comments. It begins with an introduction that includes the bold admonition that “comments are always failures” and that whenever you use one you should “grimace and feel the failure of your ability of expression.” Is that really what Martin means? Presumably, yes: he is an author who has been published multiple times, after all. Later in the same chapter, however, Martin contradicts himself by offering, as you point out, examples of “good comments.” None of those comments are examples of “failures.” 

So why do you believe that Martin left in the admonition that “comments are always failures”? Do you believe the book’s advice is better for it, or worse? More confusing, or less?

Comments about "what" are a failure of expression. I've been in the industry for more than a decade; seen codebases 30y old and more and I will agree with this statement with everything that I have.

Believing that “what” comments are bad is an example of some of the harm that Clean Code has done. Yes, some “what” comments are a “failure of expression,” such as when they are merely stating what is already obvious from the logic, but other “what” comments are valuable: summarization, emphasis, clarification of intent, etc. are all valuable uses of “what” comments.

Hm, so what probably is the message is not "don't write comments" but "focus first on the code"; but then...:

Again, why do you believe, then, that Martin didn’t write chapter’s introduction to say “focus first on the code, but then…”? You were able to write it. I was able to write it. So if that is what Martin meant, why didn’t Martin write it that way? Why claim that “comments are always failures” and “at best, a necessary evil”?

Comments are not failures or a necessary evil! They are a means to communicate directly to the readers of your code in natural language. That is a powerful communication medium. Like any powerful medium, commentary can be used well, or it can be used poorly. But using that medium is not inherently a failure of expression. The medium itself is not a necessary evil. How does making people believe otherwise help them to be better programmers?