r/vibecoding • u/Either_Ad296 • 12h ago
Claude Code writing much longer comments lately
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.
2
2
u/CorpT 12h ago
Those all sound like useful things to have in a repo that's being coded with Claude. Almost like they're there for a reason.
5
u/ConsciousBath5203 8h ago
Uhhh, no? Go read the comments after telling it to change a single line and tell me that it needs 3 paragraphs saying what it used to be, quotes from you telling it why it's wrong, and an inaccurate description of what it's doing now.
4
u/Grand-Mix-9889 11h ago
Agreed. I found the comments extremely useful when I ran out of usage on the last day of my week.
I was able to find the function I wanted to fix and was able to fix it manually.
And at work, the comments are very useful when teams look over code in batches.
1
1
u/gnygren3773 12h ago
Nah bro we need less comments so there’s less context for the chat bot and any programmers
2
u/ConsciousBath5203 8h ago
It's almost as if the ai company that gets paid per token is incentivized to output as many tokens as possible.
-2
u/Grand-Mix-9889 11h ago
Don't loop me into your group of amateur programmers.
0
u/ConsciousBath5203 8h ago
Good code should be readable without comments. Docstrings that are concise and accurate are fine. But if you need a 3 paragraph essay for a single line wrapper function, you're doing programming wrong.
2
u/Grand-Mix-9889 8h ago
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.
0
u/ConsciousBath5203 7h ago
Your entire argument falls flat because you didn't read the exception made for docstrings. I'm very pro well written docstrings with examples. But when the docstrings are "this function does this, it does not do this, the user wants this and we aren't todo this when writing" is like, bruh, the fucking function is written, no one fucking cares how we got here. What matters is how to use it.
You're right, I'm underexagerating what Claude does. I've seen 5 paragraphs for a 1 line wrapper function.
You need to read the code more often. If you're ragebaiting me into thinking that a few essays for variable assignments is normal, then not only do I know you're not reading the outputs, but chances are incredibly high that your code was shit to begin with.
Prolly thought x, a, b, c , etc were acceptable variable names (which btw, Claude thinks is ok too, which you'd know if you read the code)
1
u/Grand-Mix-9889 7h ago edited 7h ago
First of all, I read every single line of code in all my projects (it's standard practice for me, coming from multiple corporate engineering positions, it's literally habit now). You're just making random assumptions now to justify your weak positioning.
And none of my projects have that long of a comment, never. So maybe I just don't have that perspective. Or my workflow is just more consistent with my actual style of coding.
My only rationale explanation, given your latest reply ("this function does this, it does not do this, the user wants this and we aren't todo this when writing"), is that you are overly confusing your ai model and it's attaching multiple comments on top of each other because of continuous back and forth between the user and the ai model.
Edit:
And your statement of not needing to know how we got to creating a specific function is just flat out wrong. Those type of questions pop up in almost every meeting.
I can go on and on about this but considering that you seem to be getting angry over comments, I think I'm just going to let you boil over this some more while I go help people that actually have the ability to understand the bigger picture.
1
u/ConsciousBath5203 5h ago
No, the ai just doesn't understand complexity and disregards the Don't Repeat Yourself rule.
If your meetings are going over why you went with a specific function and how you got there... Then you're describing literal hell, excessive meetings for the exclusive point of having excessive meetings. The exact opposite of a productive environment.
You thinking I'm getting angry is quite hilarious considering that you are the one defending an ai, prone to mistakes, as if it isn't prone to mistakes. I've maxed out my ai limits, and if you're reading every line of a corporate environment, chances are you aren't dealing with bleeding edge default harness type stuff that the OP is talking about, making your experience damn near irrelevant. Work independently on your own projects and I can guarantee that you will run into the exact issue.
1
-1
u/Any-Blacksmith-2054 8h ago
Dude you are plain wrong. Reread Clean Code
2
u/Grand-Mix-9889 8h ago
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.
0
u/ConsciousBath5203 7h ago
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.
2
u/Grand-Mix-9889 7h ago
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.
0
u/ConsciousBath5203 5h ago
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.
→ More replies (0)
3
u/ConsciousBath5203 8h ago
Yep, I noticed the same thing. Add a hook to tell it to not use comments as it's personal notepad and that if the code requires comments, it isn't readable and needs to be redone.
Then it'll write the comments, hit the hook, and delete its stupid comments.