9 ms·

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 comm

by graemep 2mo ago

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.

nrmitchi 2mo ago
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.
pluralmonad 2mo ago
And will reference transient working docs in code comments. // No retry was added here per AC 37b in FEATURE.MD.
- jorl17 2mo ago
  // The lesson from the Parse-dont-fail-era campaign // Judged on merit from computed properties during the cursor saga // Chop 6ms due to lenience and lax-constraints vs 18ms baseline April perf measurements
  - datsci_est_2015 2mo ago
    Thanks, this sequence of 33 words alone was enough to give me a searing migraine.
    - jorl17 2mo ago
      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
      - datsci_est_2015 2mo ago
        Idk if you’re coming up with these on the spot but they’re linguistically fascinating.
        jorl17 2mo ago
        Came up with them on the spot. Unfortunately, I've been working with Claude so much it's like my brain can autocomplete them natively.
        ghostpepper 2mo ago
        it's not just you, there is research that people are starting to talk more like chatGPT. you have a gift for parody though.
jorl17 2mo ago
This! 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.
- spooneybarger 2mo ago
  I've gone back to using Opus 4.6. It's quite nice along all these fronts.
  - FiddlyPack 2mo ago
    How? I tried but got forced back onto 5.
    - arcanemachiner 2mo ago
      /model claude-opus-4-6[1m]
    - flipthefrog 2mo ago
      You can tell Opus 5 or Fable to route answers through 4.6 for rewrite
ErroneousBosh 2mo ago
Presumably you're not just blindly copying down what Claude copies out for you, but actually reading, interpreting, and understanding it for yourself?
bhelx 2mo ago
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.
- cgio 2mo ago
  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.
  - efskap 2mo ago
    But comments should hopefully explain "why", not what or how, and that kind of context is exactly what an LLM is likely to be missing
    - bonoboTP 2mo ago
      Yes, but some of that is actually better placed in the git commit messages. But of course not all.
- multjoy 2mo ago
  >It's like it has no conception This is the point.
  - bonoboTP 2mo ago
    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.
easyascake 2mo ago
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.
- porker 2mo ago
  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
cerved 2mo ago
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. Also, it reads like ass.
vilos1611 2mo ago
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. I've also written my own package for deterministically formatting comments: https://www.npmjs.com/package/comment-fmt https://www.npmjs.com/package/comment-fmt 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.
Sinidir 2mo ago
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.
bonoboTP 2mo ago
It has this tendency, but usually a sentence about this in the CLAUDE.md helps avoid it. It's annoying though that you have to add that sentence.

by graemep 2mo ago

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.

nrmitchi 2mo ago

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.

pluralmonad 2mo ago

And will reference transient working docs in code comments. // No retry was added here per AC 37b in FEATURE.MD.

jorl17 2mo ago
// The lesson from the Parse-dont-fail-era campaign // Judged on merit from computed properties during the cursor saga // Chop 6ms due to lenience and lax-constraints vs 18ms baseline April perf measurements
- datsci_est_2015 2mo ago
  Thanks, this sequence of 33 words alone was enough to give me a searing migraine.
  - jorl17 2mo ago
    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
    - datsci_est_2015 2mo ago
      Idk if you’re coming up with these on the spot but they’re linguistically fascinating.
      - jorl17 2mo ago
        Came up with them on the spot. Unfortunately, I've been working with Claude so much it's like my brain can autocomplete them natively.
        ghostpepper 2mo ago
        it's not just you, there is research that people are starting to talk more like chatGPT. you have a gift for parody though.

jorl17 2mo ago

This! 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.

spooneybarger 2mo ago
I've gone back to using Opus 4.6. It's quite nice along all these fronts.
- FiddlyPack 2mo ago
  How? I tried but got forced back onto 5.
  - arcanemachiner 2mo ago
    /model claude-opus-4-6[1m]
  - flipthefrog 2mo ago
    You can tell Opus 5 or Fable to route answers through 4.6 for rewrite

ErroneousBosh 2mo ago

Presumably you're not just blindly copying down what Claude copies out for you, but actually reading, interpreting, and understanding it for yourself?

bhelx 2mo ago

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.

cgio 2mo ago
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.
- efskap 2mo ago
  But comments should hopefully explain "why", not what or how, and that kind of context is exactly what an LLM is likely to be missing
  - bonoboTP 2mo ago
    Yes, but some of that is actually better placed in the git commit messages. But of course not all.
multjoy 2mo ago
>It's like it has no conception This is the point.
- bonoboTP 2mo ago
  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.

easyascake 2mo ago

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.

porker 2mo ago
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

cerved 2mo ago

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. Also, it reads like ass.

vilos1611 2mo ago

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. I've also written my own package for deterministically formatting comments: https://www.npmjs.com/package/comment-fmt https://www.npmjs.com/package/comment-fmt 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.

Sinidir 2mo ago

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.

bonoboTP 2mo ago

It has this tendency, but usually a sentence about this in the CLAUDE.md helps avoid it. It's annoying though that you have to add that sentence.