[TimTheTinker]

Right now the comments that upset me the most are LLM TMI-style comments that break encapsulation by talking about the behavior of specific current callers of a function right above the function definition.

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.

[fphilipe]

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.

[mnicky]

In Claude Code there are also "output styles" that are more deeply embedded - into a system prompt - and agent is also periodically reminded of them during the session: https://code.claude.com/docs/en/output-styles

Maybe these would work better for such cases.

[sheept]

My hypothesis is that Claude is inclined to write so many comments as a way of doing additional thinking

[disgruntledphd2]

Yeah, it's short form memory or something. Like writing a todo list.

[j_bum]

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.

[wrs]

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.

[jawilson2]

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++.

[mulmboy]

There's a cluster of issues like comments like "use a set instead of ..." after changing something which will just confuse people in the future. Or comments referring to irrelevant details of the planning/implementation process.

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

[boredtofears]

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.

[actionfromafar]

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.