[mrozbarry]

I think Bob Martin would generally agree. I think his gripe was using comments to make your code more readable, and that's a problem. Variable and function naming should make the code logic clear and readable. When it comes to feature requirements/explanation, that's a different thing, and a hard problem. Documenting features in code means it's only available to coders. Duplicating feature documentation from some external source to code means it risks becoming out-dated.

Syncing tickets, bug fixes, code, and feature details is a hard problem. I'd generally prefer doc-block style comments that link to feature/product documentation, which is good for humans, and probably LLMs, too. Wherever you put it, keep it consistent and searchable.

[wduquette]

Re: Mr. Martin's agreement, whether he agrees or not is not nearly as important as the impression his book gives and whether your "Clean Code"-reading co-workers agree. I know people who genuinely try to get rid of all comments as "Clean Code" suggests, and I'm glad I don't need to maintain their code.

[tmoertel]

Thanks for your feedback. I am not sure Mr. Martin agrees with me, however.

To be frank, I don’t know how to interpret Martin’s advice. If his concern was, as you suggest, that comments can be abused as a crutch to prop up confusing logic, why isn’t that what he wrote? You were able to write words to that effect. So was I. Presumably, Martin would have been able to write similar words—if that were what he wanted to say. After all, he has written several published books.

But in his book Clean Code he opens the chapter on comments with a far more radical thesis:

> The proper use of comments is to compensate for our failure to express ourselves in code. Note that I use 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.

Later in the same chapter, he undermines his thesis by presenting some examples of “good comments.” If we take his word that these comments are good, but also take his word that “comments are always failures,” we are led to conclude that good comments are failures, which is absurd.

After he wrote the section on “good comments,” how could he not realize that it refuted his thesis? Why, then, didn’t he revise his thesis accordingly? He certainly had the opportunity and the writing ability. The only explanation I find plausible is that he didn’t want to revise his thesis. He somehow thought it was helpful to instruct his readers that “Every time you write a comment, you should grimace and feel the failure of your ability of expression.”

So I’m not sure what he’s trying to say. It’s hard to believe that his opening thesis is anything other than what he wanted it to be. It’s a mystery, however, why.