I recently reacted angrily in a PR review comment after encountering one for the umpteenth time... that caught me off guard. I didn't know I was capable of that.
> 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.
Maybe these would work better for such cases.
I have a lot of CLAUDE.md rules to restrict this stuff, but realize the “encapsulation” language is something I’m missing.
It's as though the machine can't separate the chat and planning docs from the code itself and so they meld into each other. As though it can't fully grasp that the code will outlive the current session by years.
Anyway I find a checklist approach works well to sort this out. I don't consider looking at machine generated code until after a checklist covering all this sort of stuff has been applied. My checklist approach currently has about 50 items which I have the machine apply by splitting it up across about 20 subagents. Pretty silly but it seriously improves the first-pass quality vs only a few subagents. I find this checklist can effectively eliminate words like "genuine" and "landed" from the code too. Eliminates vague and made up terminology. Makes it less nauseating
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.
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.