You need to use comments, when your code doesn't make sense to the reader. A way better approach is to write code which makes sense to readers. There are cases when you need to write incomprehensible code for the sake of performance, for example, but that's rare. Even in high performance environments. Or maybe you need one for some bugfixing. But most of the strange "bugfixing", or performance "improvements" what I saw in my life was just technical debt, and coders were lazy, or had time pressure. It's really very rare when you really should use a comment. When I think about writing a comment, I immediately think through, or look into more whether there is a better approach. Usually, you can use Git, or Git+ticketing systems anyway for business reasons.

So far Clause Code's comments on my code were completely useless. They just repeated what you could figure out from the name of called functions anyway.

Edit: an obvious exception is public libraries to document public interfaces, and use something like JavaDoc, or docstrings, etc.

Most Claude Code comments answer the "what", or worse they answer the why in a way that makes no sense outside the context of that session. Stuff like adding a comment saying why they removed our changed code that they'd just written

Thoughtful comments can provide the why, but they can just as easily be a redundant re-statement of the what in the code, which llm comments quite often are.

I recall a study that said AI coded much better when in codebases with dense commenting.

I'm wondering if tsdoc/jsdoc tags like @link would help even more for context

Avoiding comments is an exercise in thinking how to rename or refactor a function, or a variable in such a way that a junior developer will be able to read it like prose, and immediately understand what's going on.

It's cognitively stressing, but is beneficial for juniors, and developers new to the codebase, just as it is for senior developers to reduce the mental overhead for the reader.

It's always good to spend an extra minute thinking how to avoid a comment.

Of course there are exceptions, but the mental exercise trying to avoid having that exception is always worth it.

Comments are instant technical debt.

Especially junior developers will be extremely confused and slowed down by having to read both, the comment, and then the code, which was refactored in the meantime and does the opposite of what the comment said.