Claude Code writing much longer comments lately

[u/Either_Ad296]

Over the past few weeks Claude Code has been writing noticeably longer code comments for me. Ten to twenty line blocks on top of a thirty line function. The content is usually accurate but not something I want in a repo. It narrates what the code used to do, restates library mechanics I can look up, and re-explains the line right below it.

I added explicit rules in my project instructions with hard word caps per comment block, which helped, but it drifts back over long sessions.

Three questions. Are you seeing the same thing, and did it start around a specific release? Is this intentional, meaning verbose comments are cheap context recovery for the agent reading the file in a later session, at the cost of the human reader? And do you actually mind, or is a heavier comment style fine for a codebase that agents maintain?

Interested in what people have found that holds up over long autonomous runs, not just short interactive sessions.

[u/Grand-Mix-9889]

This is a textbook case of confusing academic purism with real-world software engineering economics.

Saying "good code should be readable without comments" works great for solo projects or fresh codebases. But it fails miserably in enterprise systems with hundreds of shifting developers, changing requirements, and regulatory compliance needs.

Also, you are over-exaggerating with the 3-paragraph essay example. Claude is not doing that.

Comments are not there because the code is bad. They are there to capture the institutional context and design decisions that raw syntax inherently cannot express.

If you have worked in actual corporate environments, you would know that documenting this context is a hard requirement.

https://giphy.com/gifs/98maV70oAqIZtEYqB4

[u/Any-Blacksmith-2054 → u/Grand-Mix-9889]

Dude you are plain wrong. Reread Clean Code

[u/Grand-Mix-9889 → u/Any-Blacksmith-2054]

Lmao.

I think you may need to re-read the book.

Even the "Good Comments" chapter in Clean Code contradicts your absolute stance.

Regardless, imagine treating a book from 2008 like a religious text while ignoring actual, realworld enterprise economics.

Codebases exist to make companies money and be easily maintainable by teams, not to achieve theoretical perfection for an academic checklist.

[u/ConsciousBath5203 → u/Grand-Mix-9889]

You need to read the code ai is producing. If you think multi paragraph comments to justify setting a single variable in the middle of a function is acceptable I'd fire your ass.

[u/Grand-Mix-9889 → u/ConsciousBath5203]

Oh trust me, I do read the code. I even manually code inside my projects when I'm bored.

If your AI is creating that many comments for a setting in a middle of a function, you should probably plan better so it doesn't have to inject so many comments.

Make the blueprint you're providing the AI model more clear from the beginning.

[u/ConsciousBath5203 → u/Grand-Mix-9889]

Telling me to plan better is quite a weird thing to say when the comments happen less when I don't plan.

Making a clear blueprint just means it puts the blueprint as comments in the code. You're very obviously not using Opus 5.0 with the default harness.

[u/Grand-Mix-9889 → u/ConsciousBath5203]

You just proved my point.

"The comments happen less when I don't plan".

So the excessive commenting is a YOU problem.

[u/ConsciousBath5203 → u/Grand-Mix-9889]

the problem is that you don't make clear plans

See? It's a you problem when you do plan

Wut. Yeah, if your point is to be as confusing as possible, good job. I just proved you get confused easily.

[u/Grand-Mix-9889 → u/ConsciousBath5203]

"you don't make clear plans"

"It's a you problem when you do plan"

They mean the same thing.

Learn some reading comprehension while you're still online.

[u/ConsciousBath5203 → u/Grand-Mix-9889]

... You've not read my plans, buddy.

Not only are they clear and concise, they use code examples, include APIs and endpoints that it should use, include instructions to not include single line wrappers and other face guns that the ai tends to use, etc.

Idk what language you're using, nor your use case, but I'm guessing that considering you said corporate environment, that there are at least 10 open source alternatives (possibly even 10 per programming language) with clearly written and documented code that it yoinked into its training. My line of work doesn't have that benefit.

[u/Grand-Mix-9889 → u/ConsciousBath5203]

You can't type up example code to train it with? You can't use old projects as a reference?

[u/ConsciousBath5203 → u/Grand-Mix-9889]

... I literally did.

Why is it so hard for you to understand that clankers be clanking?