4 ms·
I forbid my agents from adding any comments. I review the code and add comments manually. If I can't understand something despite having the context then I thro
by hawk_ 1mo ago
I forbid my agents from adding any comments. I review the code and add comments manually. If I can't understand something despite having the context then I throw away the code instead of having an LLM generate comments to explain what it did. This way the code stays readable/debuggable by humans.
- lkjdsklf 1mo agoThat seems like a really smart workflow I wish my coworkers would adopt this. I’m sick of reading a fucking Charles dickens novel for every fucking tiny function
- Mtinie 1mo ago[flagged]
- jamesfinlayson 1mo agoUgh, this. Had a workmate recently churn out 4,000 lines of code using Claude and I'm sure half of it was just comments.
- robby_w_g 1mo agoHow do you stop LLMs from making comments? In my experience, LLMs treat requirements for code output as suggestions
- deleted 1mo ago[deleted]
- miki_oomiri 1mo agoAsk the agent to write a script to run after each changes, against the newly added code. Use that script as a super linter. That’s the only way I found to strictly enforce some rules, like the no comments rule, without enforcing them against my own changes or old code.
- eru 1mo agoYou could run the script mechanically against the diff (assuming you use version control). No need to rely on the agent.
- ks2048 1mo agoIf you don’t trust the code to write a decent comment, why trust it write good code? Of course, ensuring compilation or other checks can verify some code, which it can’t do for comments. But comments still serve the same purpose as human comments.
- Infernal 1mo agoIf I understand correctly, it’s not that the LLM can’t write a good comment, it’s that you want to be able to interpret and understand the generated code without comments - and in that process end up writing comments yourself.
- manwe150 1mo agoI don’t get that argument. Most of the time by the end of the session the comments from the agent encode tricky details that I told the agent to write down so it stops making “simplifying” assumptions. Thus comments at the end of a couple days of agent-only coding, when I start to actually read and edit the prose, contain the details which aren’t possible to know from reading the local code. It may help that my last couple sessions before I start reading the code myself are variations on telling the agent to self-review and improve the comments in specific ways, so the comments left are only those the agent thought remain meaningful at clarifying unexpected interactions between the local code and other code that needs to be referenced to understand it.
- robby_w_g 1mo agoThe actual code output has improved a lot over the past year. I’ve found it matches existing patterns better, and the code is succinct so I can easily tweak it if I don’t like the way the agent wrote it. The problem with comments is that LLMs tend to copy their verbose chat output format and insert session/prompt specific details. It makes me think that LLMs aren’t constrained in their comment output the same way they are with their code output
- embedding-shape 1mo agoAdd "Don't add any code comments anywhere" to your system prompt. If the model doesn't follow this, you want to start using a better model ASAP, because SOTA models for the last year or so, been able to following this without an issue.
- yehoshuapw 1mo agoI've come recently across arxiv 2604.20911 which claims "do" rules persist much better then "don't" rules.
- embedding-shape 1mo agoAlright, what you'd put instead of "Don't add any code comments anywhere"? I agree with the general guidance, but it's a general one and not applicable for everything. Some things cannot be expressed in a "do" way rather than "don't".
- yehoshuapw 1mo agoI don't know. I fully agree, and never did really try out this in depth yet. I suspect rules with negations are not the same as don't rules, but unknown if really true, if so: "when writing code do not add comments, code should not need it" may work
- embedding-shape 1mo agoYour proposal is still a "Prohibition-type constraint" that the paper you linked earlier say "isn't good". Some of these constraints we want simply aren't possible without adding "do not" somewhere in the line, even if you prefix/suffix it with other stuff, as you noticed yourself :)
- wongarsu 1mo agoI don't think changing "don't" to "do not" is what the paper authors had in mind I use things like "Your code should be self-documenting, so as to require as few comments as possible. Add comments to explain "why" or give important context not apparent from the code itself, but keep them to necessary comments only" But that's a much laxer rule. I don't think you can truly express "no comments, ever" without a "don't" rule.
- nicky0 1mo agoIn my experience, Claude adds loads of comments, but Codex (GPT-5.5) never adds any.
- imagetic 1mo agoMad props to you for that. Smart.
- solatic 1mo ago> This way the code stays readable/debuggable by humans. Please take the following as expressed with genuine curiosity: Do you not use an editor with syntax highlighting and collapsible comments? At least on JetBrains you can configure the editor to collapse all comments on open and to have the comments displayed in a low-contrast color. This way, LLMs add a bunch of comments, but it doesn't affect your actual experience in trying to read the code. If you encounter code that seems inexplicable, then and only then would you expand the comment to see if that helps you understand.
- metek 1mo agoLLM comments for code are almost unfailingly completely redundant or impenetrably verbose bordering on word salad.
- shunia_huang 1mo agoSometimes I try to add comments in a new session and the agent just don't have enough context for it to give a comprehensive sentence with full context on the why, then the agent will just describe what it does. Human comment is in another level to answer the questions mainly like "why do it like this" for the later collaborators or the forget-ed self, so the important blocks live when it is needed and can be eliminated when it does not.
- jodleif 1mo agoAlso, the language model might not fully understand the code then add a comment, then the next iteration will treat assumptions in the comment as the truth.
- digitalPhonix 1mo agoI think “This way the code stays readable/debuggable by humans” is a proof by example (not that the generated comments are necessarily bad). If the human can read/understand it well enough to comment it, then it is readable by humans.
- 1mo ago
- dcuthbertson 1mo agoI'm not convinced, yet, that eliminating LLM-generated comments is the right path for me. I do review everything written by an LLM and some comments are actually pretty good, but sometimes I'm just too tired to try to figure out how to reword an oddly worded one. I just added Sanglard's rules to my ~/.claude/CLAUDE.md file, did another code review, and found some LLM-generated comments were really hard to understand. I think they're due to invented metaphors and flowery language instead of using standard terms, so I've added this: - Comments must be literal. Don't invent figurative language for what a plain technical term already says — write "rows still reference it," not "rows still wear it." Improving LLM code generation is an iterative process. I'm glad people share their efforts to improve it.