This is what has been frustrating me most lately. Even though I have a rule in my global CLAUDE.md that says:

> Only write comments to explain the why when it is not obvious from the code (rationale, gotchas, constraints). Do not comment on the what — well-named code already says it. Do not comment on how a framework works.

It still keeps adding these bad comments. When I then ask it to review the comments based on my preferences it then deletes most of them or improves them.

Today I asked Claude why it disrespects my preference and it said that the surrounding code was like that and it followed that style. It suggested I add this line to my global CLAUDE.md file:

> The comment rule above beats the style of the surrounding code: neighboring files with what-style comments are not license to write more of them, and comments carried along when porting or copying code must be re-judged against the rule, not kept for consistency.

Let's see if that improves things.

Yeah, agreed. These have started popping up a lot more recently, where I get a 5 sentence paragraph explaining how function overloading works in c++.

This drives me nuts as well. I hate also hate when LLMs use plan-document references in comments/doc strings too. “Landed in stage 1…”

I have a lot of CLAUDE.md rules to restrict this stuff, but realize the “encapsulation” language is something I’m missing.

Claude Code and Opus 4.8 love to describe changes in comments (perhaps because that’s what’s on its “mind” at the time), like “this used to do A but that did a bad thing so now it does B”. I’ve almost convinced it that changes go in the commit message, not the comments.

Well, on the one hand, Hyrum's Law: "With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody."

so that can be useful information in some situations.

On the other hand, what a horrible out of date mess of comment that can turn out to be a little bit later. Taken as gospel by the next entity (human or llm) to massage that function.

I have tried prompting it out and providing strong guidelines in my AGENTS.md against it, but I still get _way_ too many useless "explain the code" style comments no matter how much I try. I usually have to do something like "Look at all commits in the past X days and remove (DO NOT TRIM) all comments that are not truly exceptional"

Normally when I can't get claude to follow a prompt I try a lint hook, but it's tough to lint something that subjective.