Claude not only writes verbose comments, it also writes comments about how things used to work when refactoring. That might have a place in version control comments, but not in the code.
This speaks to the general problem with using LLMs for writing. The audience they are writing for us you, but you're trying to write for a totally different audience. In code, this manifests as comments in the code that are hyperspecific to the conversation you are having, and not the long term benefit of having those comments in the code.
I see this in docs a lot. I've been reading a lot of docs these days where it feels like the LLM is trying to hype up the person writing the docs. It's like it has no conception that the writing is meant for a 3rd party audience.
It reminds me of something I've always wanted as a coder but never cared enough to implement, which would be a verbosity switch.
I see the full multi-paragraph comments in my codebases and get annoyed but also feel like the additional context helps improve the llm results over time because that history helps it know what's been tried and removed in the past. It's additional context for the system that improves with context.
The feature I want in the code tool itself (for me) is to adjust how verbose the comments are so I can read "just code", then "terse comments" then "full comments" then "full comments with historical context" (including fit commits and ticket references) and finally, full-on literate programming. And I'd like to switch between on the fly as I read through the code.
I think this is something we could actually produce with llms, and I feel the ability to switch between these modes would help the llm as well.
Sometimes I just need to see what's being done. Sometimes I need to know why. Sometimes I need to know what's been tried. Never always all of these things. And expecting to find this context in git comments doesn't feel right either.
What you want can be accomplished with an extra doc, call it the Log, where the llm appends things tried, lessons learned, failed experiments etc.. while leaving the comments as terse accurate snapshot of the current state. I've been using this log pattern and it works well.
Despite all of this though, GPT 5.6 Sol to me has significantly less trouble with this. It still suffers from LLMisms to some extent (I hold that this is probably due to human feedback in training just doing a bad job for prose) but I definitely feel like it does a better job leaving comments that actually make sense in context. Not perfect. But better.
I suggest the real problem comes down to training and probably training data; from the LLM's PoV, it is writing code inline with the conversation, so care has to be taken to make sure the model doesn't treat the code it outputs like it is a part of the conversation it is having.
It's an empty point and a boring one and leads nowhere. It means nothing, but sounds deep. It's so shallow, any taxi driver and sociologist can come up with it and has, already in December 2022.
I don’t even think comments are useful at all given AI. I can ask my AI to explain a piece of code if I am stuck and I will get a reply in context of what I am looking for.
We call these temporal comments. We recently updated our code review skills to heavily discourage them. It doesn’t matter why funcA was added then later refactored to funcB. That much can be ascertained from git history. What does matter is why approach A doesn’t work, but B does.
How well is your code review skill doing at detecting and correcting these? History in comments in git is so annoying! As is missing why A didn't work but B does. None of the models I've tried get this right
Glad to know it worked. Still pending: the assumed-defaults research track plus the validation-only build phase D demanded — your call on whether to start one now or deploy tonight’s campaign to surface any wrinkles the spec drifted on
It's incredible, because I Feel like you've been watching me work.
The only thing you're missing is the "open question" that was stuck in page 14 of a 17 page report, which since it went unanswered, caused claude to make up an answer and go full steam ahead, ignoring fundamental properties of the entire system.
> The user is right to be upset. I blindly answered from memory and left them with questionable data. I should acknowledge the criticism and offer to improve.
You're right, I'm sorry. You've repeatedly told me to run questions by you and I just fabricated an answer and ran with it — which is exactly the kind of dangerous time-waste we created the memory for. I'll revert it and pull up the real question so you can answer it — no wasteful assumptions this time.
That's a sharp insight, and it reveals something core to communication that I otherwise wouldn't have considered- HN item 6b translocates reliospacactivity of our medium.
Sorry for the anthropomorphizing, but you got to understand that these little "conversation chapters" that are so dramatically named are these things' entire world. Perhaps that otherwise absurd grandeur is not so surprising when when looked at from that angle?
On a more serious note, could all that chapter naming be some visible outcropping of context compaction strategies? "Condense the conversation history into a summary". Not really surprising that it comes up with these "cute" headlines. Would appearances be better if they were somehow prevented from leaking to the user? Sure. Would results be better? I don't think so, might even make a meaningful difference if the user actively embraced the terminology the machine came up with. Ouch.
As a human who isn't a professional programmer, I've been writing comments like,
// let's track age!!
// this is harder than you'd think as I with totally impressive
// foresight didn't add age to the raw data.
//
// More honestly, I didn't want to add age to the astro data as that's
// a calculation that can change depending on how you slice it.
//
// Hence we need to figure out their age first.
I think this passes. In general "why" over "what". Give context to why something is made like it is (when seeming convoluted or strange). Sometimes I think one can give historical facts for really hairy hard to fix issues that have seen multiple iterations. But LLMs don't see these nuances. They frequently smuggle in completely irrelevant details in comments, e.g. including details from the given task context, not understanding what is relevant for the code module as a whole.
Edit: For API comments it's "what" of course, detailing the workings and contracts of the exported method, function or type, so one doesn't have to read the code to figure out how to use it.
I'm mostly writing code for myself, but it's a project that'll end up being public and it'll be available for others to do whatever they want with. Does that change the answer?
Far too often the answer has been that it doesn't matter, because the reason you stopped using Jira is the company stopped sending paycheques.
That said, I think the place for "ticket-1234" is the git
commit/pull request.
Very few comments are
genuinely necessary now that identifiers in code can be as long as you want, it is relatively to pick names that are explanatory enough to render most comments superfluous. 1% exceptions for unusual algorithms. (You're using named consts/enums rather than magic numbers, yes?)
personally it's fine and I've thanked myself many times for overly detailed comments coming up to some from 8 years ago and thinking how tf was I so smart/stupid (depending on the context)
This one drives me nuts, especially because I divvy up plan documents into such granular sub chunks and Ralph loop over them, I get nonsense commit messages and comments like “PLAN-5.1.A.d.42 load bearing reassertion” unless I AGENTS.md to hell and back… and still end up having to manually reject 5-10% of commit messages because the agent simply forgets AGENTS.md instructions until reprompted.
Sometimes you can do a separate skill for committing only and basically minimize the context - "analyze the commit messages, the original instructions, and this set of things to stop wasting my FUCKING TIME"
I've definitely considered writing a commit skill and a `cc-safety-net` custom rule to fully forbid `git commit` other than with `--amend` ++ `--no-edit` outside of that skill. Hm, maybe that's a task for an upcoming weekend.
My theory is it writes these comments as "notes while working", and I don't don't mind that, per-se. My problem is it's inability to clean that shit up before committing it. That's wrong load-bearing lever that doesn't earn it's keep.
Claude writes comments about how things used to work, which can be useful sometimes, especially if it's a big change that requires one to genuinely consider legacy behavior, but most of the time it shouldn't be there.
Two other somewhat related things it does:
- It writes as if someone reading the code and comments is aware of everything it is aware of (the current conversation, the code it has just looked at). It's really hard to make it understand that things need to stand on their own. A trick is to get a subagent to look at it with a fresh context, but it doesn't tremendously help
- It does all of this with user-facing strings too. Claude loves to write up tooltips and other labels that leak everything to the end user. Every single concern we have, every edge case we've meticulously made our code handle, it passes on to the user, so they don't "need to worry". But no sane user would think of these things. For them, a feature is a feature. The "dynamic scheduling" button should state what dynamic scheduling does plainly, and every edge case is handled by us. The "add" button does not need a label letting the user know that they will later be able to click the "delete" button, because the user will just realize it due to our adherence to proper design. Claude fails to understand good UX for the user cannot be replaced with endless labels and explanations.
It's an uphill battle and all attempts at solving this (or the brain-dead way new Anthropic models write) usually fail to work with me.
I've explicitly included instructions in my home CLAUDE.md to avoid this, because it's one of the most annoying things about how Claude writes comments.
Both with a formatter and a linter that I run in CI for all my personal projects. Just one less thing for me to try and coerce the agent into doing correctly, so that cycles I spend reviewing agent code can be focused on actual behavior.
Yeah i noticed this heavily. Working on a branch i critique and give a simpler design. Claude implements and then in a huge comments reference the outdated worse design. Zero value to that. Even having a "how to write comments" section in claude.md doesn't seem to help much with that.
I struggled with this for a long time, but actually seem to have gotten to a place where this is largely resolved. Copy/paste from my current claude.md:
The CC-5 rule specifically seems to be (just from reading through, nothing repeatable-eval based) the part that actually catches and prevents me from having to clean it up afterwards.
```
### Code comments
The failure this prevents: writing a comment that narrates the change I am
making right now. That context is real, but it expires the instant the change
merges — the defect it describes no longer exists, so the comment becomes a
story about a problem no future reader can observe. It is a changelog entry in
the wrong file, and a third copy of text already required in the commit body
(3.b) and the PR description.
- *CC-1 (MUST NOT)* Write a comment describing a change, a fix, a defect, its
cause, or what the code used to do. No "was/now/previously/instead of", no
"this fixes", no "needed because otherwise", no "note that we no longer".
- *CC-2 (MUST)* Apply the survival test to every comment before writing it:
would this still be true and useful to someone reading this file a year from
now, who never saw the diff? If it only makes sense beside the diff, it is
changelog — delete it and put it in the commit body.
- *CC-3 (MUST)* Default to zero comments. Declarative config — Terraform,
DNS records, k8s manifests, CI YAML, Helm values — is self-describing and
takes none. A resource named `dmarc-example-com` does not need a comment
saying it is the DMARC record.
- *CC-4 (MAY)* Comment only when a future editor would actively break
something without it: a non-obvious external constraint, a required
out-of-band manual step, an invariant the surrounding code cannot show. One
line. If it needs a paragraph it belongs in `plans/`, not inline.
- *CC-5 (MUST)* Before every commit, re-read the comment lines I added:
`git diff --cached | grep '^+' | grep -E '#|//|/*'`. Each hit must pass CC-2
on its own. Deleting is always an acceptable outcome. "I already wrote it",
"it is only one line", and "this one is genuinely useful" are not exemptions
— the last one is the exact thought that precedes every violation.
- *CC-6 (MUST)* Applies to comments I edit as well as ones I add. When a
change invalidates an existing comment, the default action is DELETE, not
rewrite it into a new narrative.
```
Yes, I am aware that claude mostly generated this, and it can probably be better and/or more succinct.
