Claude can add comments in code that are better just living as a comment on the PR.
You'll ask it to do something and it'll comment the code with an answer to what you asked it, rather than just explanatory comments to whoever comes after.
There's also a second issue that if the code is actually incorrect, the comment can nevertheless bolster the case for it.
I found that Claude would litter the codebase with what felt like notes-to-self. Sometimes it would make an abstraction that wasn't very well thought out and when I pushed back on this choice, it would usually go with something more along the lines of what I suggested in my pushback, but left a comment like "use the git CLI instead of re-implementing git" or something.
It felt like it was commenting on the diff sometimes instead of what the code was doing.
Those verbose comments provide context for why something is there way it is, so it can take those decisions in account when making changes in the future.
It writes out stories describing what isn't there or what used to be there. It's usually not helpful, just noise. It also likes to write it in very verbose AI-styled prose.
And the way they are written is rather unhelpful: '//this not cosmetic: this css helps the user understand where he should click'. The 'this is not' pattern is useless at best.
It's likely not helpful to you, but it is to Claude. Basically a memory entry at the exact point of relevance, with the same caveats. One advantage though is it survives cloning, so another using the project benefits.
It does visibly use a few more tokens in the short term. But it hurts Claude's ability in the long term if removed because it has to either think more every time it encounters that section in the code (more invisible thinking tokens used), or there's an increased risk of making a maladaptive change without context. Heck I've been bitten enough times already by it, though more recently it's cross project concern where Claude rediscovers some root cause that was already found and documented (I have it save a centrally-located writeup for things that took serious work to learn, when I remember, but I still need to make that knowledge pool known to other agents/sessions without having to manually prompt each time) elsewhere.
Problem is today's LLMs don't have the long term memory that humans have, and so remembering the reason behind a given change/decision has to be preserved in some way if it's non-obvious. Hence why there is {AGENTS|CLAUDE}.md, the auto-memory system, and 1001 variants of memory implementations in the wild. All are trying to ensure that LLMs can have the context they need at the location and time they need it. And you want to block Claude from using a technique that it natively finds helpful.
If that were the case, the habit would have been trained out of it by the LLM researchers at Anthropic, etc. As for humans... well Idk about you but I'm not reading every line of generated code. I read the live transcript, and only dive in if something is off that the agent isn't resolving.
I'm certainly reading the code and comments, and I encourage all of my team members to do so. You are assuming that this excessive and nonsensnical comment choice is deliberate. It cannot be, or should not be because it regularly confused our team, and it regularly confuses claude also.
Also many many people keep saying the same thing and you keep repeating adnausium the same tired comments. I get it, you think the comments are great and are valuable.
The concensus in this thread is that for multiple reasons the excessive comments are in fact actively harmful. The listed reasons are:
1. Document the conversation, not the code — narrate the back-and-forth that produced the change rather than what the code does
2. Reference intermediate states that never shipped ("previously X, now Y")
3. Cite plan documents and session artifacts (`per section 2.1 of addition-implementation-plan.md`) meaningless to a future reader
4. Belong in commit messages or PR comments, not source files
5. Go stale immediately — describe a state the code is no longer in
6. Launder incorrect code as intentional, making bugs harder to spot
7. Build a false Chesterton's fence around mistakes
8. Use defensive prose ("this is not cosmetic", "prevents the critical bug that shipped once") that asserts importance instead of conveying information
9. Describe what the code doesn't do — relevant in the moment, not in the codebase
10. Confuse later agent sessions, sending them to read irrelevant files
11. Consume context tokens on every read
12. Force reviewers to manually delete the litter
13. Resist correction — telling Claude to be concise doesn't durably stick
Please consider that your opinion may need to adjusted.
Why wouldn't it be deliberate? Do you think it's happening without the Anthropic team's go ahead? Or maybe they aren't aware that it's happening?
Yes, I "push back" because an LLM using any means at it's disposal to improve itself is just a logical thing, and I have seen it help Claude. Because I read the live transcript (so I know what it's doing and can steer if I see it veering off), I've seen quite a few times the comments it made previously give it some extra context, which more times than not leads to it self-correcting. There are a few times where it becomes a bit confused because some comment block is stale, but it usually surfaces this confusion, which again I will usually catch and properly steer because I read that live transcript.
It's very similar to someone scribbling notes in the margins or between the lines in the pages of a printed work. Sure it looks messy to others (I personally would hate reading something with another's scribblings), but it's a sensible thinking aid for that person. And if another person reads some given note, they can always question the writer about it, if deemed appropriate.
No, I'm going to take a stance similar to Galileo and "stick to my guns" despite what others were/are saying, because it's not only empirical (I've seen it), but also logical (it makes sense). LLMs need extra context for non-obvious things, and without it, they can easily lose their way. There are many tools out there trying to solve the extra context problem with various degrees of success, but I say the most efficient method is having that extra context always available at the point where it's relevant, so there's no need for the agent to waste tokens making tool calls to get it, or even waste thinking tokens wondering if it should call a tool in the first place to see if there is extra context. Just like a human rereading a work will naturally encounter any previous notes they made between the lines or in the margins, and trigger related recollections. And yes, human-scribbled notes also become stale and irrelevant, but that won't stop the human finding at least some of it useful and timely. In either case, the quality of the notes taken could likely use improvement, but blocking the at-site note-taking itself leads to generally reduced effectiveness.
> Why wouldn't it be deliberate? Do you think it's happening without the Anthropic team's go ahead? Or maybe they aren't aware that it's happening?
Yes that’s exactly what I think. I also don’t think the team was aware that opus 5 talks like an overcooked gibbon either. And what’s more I’m certain that it will do neither very soon.
I just had Perplexity check out the Bun code to get an idea of how "comment crazy" it is[0]. Based on the results I'd say it's good signal that Anthropic is pretty aware that Claude loves to comment the non-obvious, and this is a desired feature (unless they're somehow clueless about what's happening in a signature public-facing project). Which, again, is a logical take so there isn't a profusion of auto-memory entries, oversized CLAUDE.md, etc which all require extra tool calls or are always in the context window.
What you need is RAG and better context management. I use vornik (it has plugins for both codex and Claude) that gives both the long term memory you mention. Hope this helps.
Sounds like a bunch of extra tool calls, and dependence on a hopefully accurate retrieval system. Vs the extra context just being available where it's relevant.
Confusion usually surfaces immediately, so it can be steered properly. Being sure of a decision that turns out to be wrong usually means a bug that could bite when you least expect it.
No it doesn’t. The comments end up complicating simple tasks, and if you open the repo after a week it takes a while to find out why Claude is reading irrelevant files or replying about irrelevant things
If that happens you do notice that something is off though, and can steer accordingly. Unless you aren't monitoring the agent, which I suspect is the real issue here; people send a prompt, go do whatever else, return and send the next prompt or use/release the artifact, without reviewing the transcript to see how Claude - or whatever agent - did.
I don't notice it because, agent running in full-auto until there is a PR to review or decisions to make. If I wanted to go step-by-step, I'd write code myself with LLM auto-complete.
I only leave meta-comments in if its actually helpful (i.e. it goes in a wrong direction without it)
I run Claude Code in auto-mode (or bypass when sandboxed) and still am able to monitor the transcript because - possibly by design - it works slowly enough that I can keep up and usually steer; there's no going "step-by-step". In contrast, whenever I use DeepSeek Flash, it goes so fast that I'm unable to keep up, so I primarily prompt it via Claude and also have a separate review in a fresh session, usually also by a Claude.
Except you have to expand to see writes, and if sub-agents are used, suddenly you need to monitor N transcripts. Workflows are even harder to see as they go, but workflows are what make it not have amnesia about rules you set for it. Workflows also can't be steered.
Claude Code is just about geared towards "prompt it and let it do its thing"
I don't look at the writes unless there's something off in the prose or I know my request might be problematic/vague. For the most part the prose is a suitable signal for how well Claude is doing. I really dislike subagents as their transcripts are obscured, so I made something[0] to remedy that. I depend a lot on being able to see not only what the agent did, but the series of decisions that got it there because that helps me to improve my prompting skills as well as to determine if I should prompt a skill for X or memory entry for Y.
If they have in mind what I think of when I think of claude comments then frequently they are only relevant to the back and forth that produced the code and are exaggerated to the point of being misleading. A very common example is to land on something that isn't quite right or doesn't quite work, prompt an adjustment, and then the adjustment will have some grandiose prose about "preventing the critical bug that shipped once." People just need to clean up such litter manually but it would be nice if the models generated less of it.
The story of how the code got to a certain state belongs primarily in git commit messages, not in comments. Comments should serve to aid in understanding of the code, highlight footguns or hidden dependencies, etc.
Claude very often litters code with comments about decisions that were made within a single session/pull request, its just noise.
Those massive comments generally refer to intermediate states that never shipped, making them utterly useless, noisy and confusing as a permanent artifact. They're sometimes useful to reviewers, so a commit message or pull request comment is much more appropriate.
That's your perspective. For Claude that's an extension of its thinking, which makes it work better. Just like the person who takes notes so they have references for later. Take it away and you're negatively impacting outcomes.
No, it's the other way around. If you put a comment "don't do foo" in your code, you're biasing future readers, human or artificial, to think about foo when you explicitly want them not to.
It isn't about making readers not think about foo. It's about biasing thought about foo in a particular direction. And I've seen it work multiple times: agent mentions it encountered X comments in the code and revised its action as a result (yes, I read live agent transcripts).
If one needs to dig history, then git log -p and similar are way more useful and reflect the real history rather than LLM inference about it. Comments reflecting the goal are more useful as neither history nor code itself covers it.
Looking into git history is an active decision that's usually only done after something undesirable happens, and now there's the need to try and find why. Better to have the context passively loaded as part of working with the relevant section of the code, and likely prevent that something from even happening in the first place. Think Chesterton Fence.
Why is fewer comments a good thing?