Claude Has An Over-Commenting Problem
As a developer that has been using Claude Code (mostly the Opus & Fable models) for the last few months, I feel I can safely conclude that Claude isn't doing a good job when it decides to write docu-comments - comments that document code changes. While some of the comments Claude generates as it makes changes have been fruitful, in my experience most of them have not been. The pitfalls I commonly see Claude fall into include:
Documenting the old state of code as it changes it - this is what Git history is for.
Adding comments when changing simple CSS styles - this is unnecessary documentation. We don't need a 2 line comment explaining why you changed
p-4top-0.Writing comments when it adds a package - simply unnecessary.
Putting comments in the wrong place - for example, writing a comment that explains why it is changing something, several lines above where the change actually occurs. Poor colocation.
Essentially, in my experience, Claude seems to feel it is necessary to write a 2-6 line comment every time it makes a change in how something functions. That's not why we write comments. We write comments when code is not very easy to understand, or may be confusing. We don't write in-line code comments because I changed this, so let me explain why.
In some cases, updating the CLAUDE.md file helps with nudging Claude in the right direction. However, this is not a foolproof fix. Our team has placed a detailed "Write comments sparingly" instruction in the file that explains when it should and shouldn't comment something. Yet, many times Claude will write code that directly opposes this instruction, and we have to remind the model that the directive exists - defeating the purpose of the file in the first place.
Why I'm writing this
I feel like a call to action is necessary here. Between the vibe coding trend, which is still prominent today, and the fact that more developers are using agentic AI now than ever, there seems to be a growing question of whether AI generated code should be reviewed, and to what degree. Some say it depends on the project and how important the application is. My take: Code should always be reviewed if you care about code quality.
Real examples of Claude's over-commenting problem
Take a look at this code Claude recently added in a PR I reviewed:
Think about it: do we really need to add a comment every time a CSS class is added or changed? What will this codebase look like 5 years from now if Claude is allowed to do so without anyone intervening? To be fair, Claude does not write a comment for every class it adds, but the amount of times it does add a comment that isn't necessary is concerning. I also realize in some cases, the background / context is necessary and genuinely helpful, so we shouldn't be too quick to delete any comment AI writes without weighing it against the original problem and the change made to fix it.
Here's another example:
Here, Claude felt it was necessary to write an orphaned (no adjacent code) 3-line comment explaining where OnboardingCompletedDate was moved to and why. However, this kind of information is exactly what Git history is for. Does Claude really need to document that a property used to exist on this class and was moved to another class, and why? No, because Git history reflects that, and proper Git comments (or ticket descriptions) will explain this - no code comment needed.
Again - in a world where we aren't reviewing Claude's contributions, just imagine how many of these comments our codebase will have 5 years from now, and you'll understand why I'm concerned. I have noticed that Claude will occasionally delete older comments it wrote that aren't useful anymore, but will that always happen, and how and when will it happen?
Should we care about code quality in 2026?
A fair point that can be made is we as developers aren't reading code as much these days when something goes wrong in our application. In modern agentic AI workflows, we simply prompt Claude to fix the problem. If Claude is reading the code and not us, does it matter if there are a bunch of unnecessary comments around, or completely dead code for that matter (which Claude isn't good at removing either)?
In my opinion, you & your team own the product. It's your codebase (your company's, your client's, etc.) - not Claude's. If you care about the quality of the product you are shipping (which we all should as developers), then you should care about the quality of the code it runs on. It's that simple.
I think of it like this. Picture your product as a person in a tuxedo. End users just see the outside - the tailored, clean tux, the bow tie, the fine dress shoes. Everything looks fine. On the other hand, developers and engineers see (e.g. in PR reviews) what's beyond the tux. If the quality of the code is allowed to deteriorate, the end user may remain happy because it still works, but we are no longer proud of what we are shipping. The less we care about the quality of what we're shipping, the more we disassociate from the product itself.
Does Anthropic need to do something?
This issue with Claude over-commenting things isn't really a major problem with the model. I'm sure there are much more important things that should be fixed or improved with Claude right now. Yet, I do wonder if Anthropic has coded Claude specifically so it over-comments things it changes. I also wonder why Claude needs to be manually reminded of instructions in the CLAUDE.md file so much. Are the directives I've added to CLAUDE.md not specific enough? Or is it an actual programming fault with the model?
I suppose as time goes on and more users report issues such as these, eventually Claude will improve enough where these are no longer a concern. I have seen Claude make major headway in its reasoning and thinking in versions past 4.6, so I'm optimistic for the future.
Conclusion
These are just my thoughts on the current situation with Claude and its commenting algorithm. It's concerning to the point where writing this blog post felt necessary. I hope you enjoyed the read and let me know your thoughts in the comments, or write to me on X.
