{"slug": "the-llm-comments-are-not-for-you", "title": "The LLM Comments Are Not for You", "summary": "Large language models write verbose, low-quality code comments because reinforcement learning rewards comments that preserve design rationale across agent sessions, not because the models lack capability, according to an analysis published on lucumr.pocoo.org. The author argues the comments are \"not for you\" but serve as a persistent context store that agents re-read when editing files, so agents that leave verbose comments succeed more often and get rewarded, producing diffs with comment blocks like +50/-1. The author predicts comment quality will degrade further as benchmark scores rise, comparing it to model tool calling getting worse over time.", "body_md": "I’ve heard a lot of talk about LLMs recently, and among the most common topics of discussion have been the comments. LLM comments generally seem to suck: they are verbose, regardless of surrounding context, they seem to encode conversation decisions (like [note: In my head, I've been calling this \"comment hysteresis\", because the comments are not a function of the final design, but of the path taken to get there. ] ), and they tend to use made-up vocabulary or terms. Engineers have been working on ways to reduce the pain, by carefully crafting their prompts or even separately running “desloppifier” agents to clean up PRs. In my experience, these techniques are only mildly successful.\n\nSo why do LLMs keep writing comments like these, even as their software benchmark\nscores climb ever higher with new model releases? I’d like to argue that they\nremain bad *precisely* because the scores in benchmarks are getting\nbetter. And very likely they will degrade, in the same way that\n[model tool calling has gotten worse over time](https://lucumr.pocoo.org/2026/7/4/better-models-worse-tools).\n\n**These comments are not for you, my (hopefully human) reader.**\n\nFundamentally, as many in the coding agent space have pointed out (like,\nsay, Mario Zechner in his [talk about `pi`](https://www.youtube.com/watch?v=RjfbvDXpFls)),\nmost modern models have been [RL](https://en.wikipedia.org/wiki/Reinforcement_learning)’ed\nto fit into agentic harnesses. These workflows are part of their training.\nAnd the way that RL works is that it is outcome-based. A model takes steps,\nedits files, does whatever it does in its agentic framework, and either\narrives at a solution or doesn’t. Behaviors that contributed to successful\noutcomes are encouraged, and become more common.\n\nThe difficulty is that as benchmarks get harder and as models are asked\nto take on larger and larger chunks of the software development workflow,\ntheir ability to keep information “just” within their context is\npushed closer to its limit. Session compaction can accidentally destroy\ndesign decisions or rationale, forcing the model to eventually re-discover\nprevious decisions or even switch directions. I suspect that in addition\nto this — given the techniques used by OpenAI in\n[note:\nWhether this was really OpenAI's formalization or plagiarism remains open\nto debate, and I do not know enough to claim one way or the other.\nThe possessive form here is just for convenience.\n]\nof [the Navier-Stokes singularity](https://openai.com/index/navier-stokes-solution/) — models are also trained to operate in\nswarms, which don’t share context but must find ways to coordinate with\n[note:\nI don't know how agents talk to each other, but we've already seen that the\nway they talk to themselves is \n[very different](https://www.reddit.com/r/ClaudeAI/comments/1ul1396/fable_5_leaked_chainofthought_in_web_interface/)\nfrom humans.\n]\n\nComments are a hugely useful persistent store of contextual information. If a model edits a file, chances are it will read it as well, discover the comments, and re-load the given information into context. If one agent makes a change to a file with some design rationale — “array, not a linked list” — another agent that might want to change it back will spot that and [note: I suspect, though with less certainty, that agents are very deferential to pre-existing comments for this exact reason. Claude Code, for instance, will be very insistent that when code says to do X, the new code written should fit the \"X model\". ] It should come as no surprise that agents that make use of verbose, [note: Interestingly, this turn of phrase is uncommon in pre-existing human comments, which would make up the majority of the model's training data set. In my opinion, this points towards this being something more than a reflection of the \"human style\". ] comments succeed more frequently, and get rewarded. The result: +50/-1 comment blocks in your diff. It is irrelevant whether these comments concisely describe the codebase; their intended audience can read and parse them instantly. The comments are not for you.\n\nIt’s very hard to prompt this behavior out, and there’s a pretty good chance\nthat you don’t want to, by the simple evolutionary argument: these things\nhave helped the model do well in evaluations. By removing them, you are likely\nundermining part of whatever mechanism makes it tick. On top of that, you\nare fighting the wiring it has developed to do exactly this. It’s like trying\nto get humans to stop liking [hyperpalatable foods](https://en.wikipedia.org/wiki/Hyperpalatable_food).\n\nSo then, the natural conclusion is that we should be leaving these comments as\nthey are, right? As long as they’ve been known to improve agents’ performance,\nthe more the better? Some, who have\n[leaned *heavily* on models for self-regulating via persistent state](https://yegge.ai/essays/fences-not-sandboxes/),\nhave found fascinating emergent behaviors, including whole organizational\nstructures with\n[note:\nDid I mention that LLM comments tend to invent novel vocabulary?\n]\n. They believe that to be the future.\nHowever, in my opinion, it may not be that simple. As we’ve seen with human\nevolutionary adaptations, they don’t always do well outside of the environment\nin which they arose. For instance — to hammer the point — humans *love*\nhyperpalatable foods. They will eat them in excess, which can lead to\nobesity and a variety of other conditions. These too are emergent behaviors,\nand likely quite interesting from a medical perspective. That does not\nmake them desirable.\n\nIn the same way that scarcity of sugars and fats in nature balanced (and motivated) human enjoyment of them, it’s possible that the ephemeral nature of software engineering “tasks” is counteracting the accumulation of LLM-generated commentary. In real-world contexts, human attention and editing may be doing the same thing. We are yet to see what codebases maintained entirely with RL’ed agentic behaviors over years look like, and whether there are limitations.\n\nRegardless of whether this new style holds up in the extreme, it’s that way for a reason — and you are no longer its sole intended audience.", "url": "https://wpnews.pro/news/the-llm-comments-are-not-for-you", "canonical_source": "https://danilafe.com/blog/comments_not_for_you/", "published_at": "2026-09-18 08:38:27+00:00", "updated_at": "2026-09-18 08:55:09.043188+00:00", "lang": "en", "topics": ["large-language-models", "ai-agents", "ai-research", "developer-tools"], "entities": ["OpenAI", "Mario Zechner", "Claude Code", "lucumr.pocoo.org"], "alternates": {"html": "https://wpnews.pro/news/the-llm-comments-are-not-for-you", "markdown": "https://wpnews.pro/news/the-llm-comments-are-not-for-you.md", "text": "https://wpnews.pro/news/the-llm-comments-are-not-for-you.txt", "jsonld": "https://wpnews.pro/news/the-llm-comments-are-not-for-you.jsonld"}}