I got comments on a pull request recently that I found deeply annoying. “This comment is difficult to understand.” “Same here.” “Same here.” I wanted to throw a pen across the room. To me, these weren’t particularly difficult to read, were technically accurate, and fully-described the behavior of the code. What gives? Then I started thinking about this from an outsider perspective. As the person closest to this code, all of this was perfectly reasonable. But what about someone less familiar with it (e.g., the reviewer)? A junior engineer? Even me at 2am?
Complexity without function is just performance. LLMs are trained on a vast corpus of data including scientific papers, sophisticated technical writing, and comments in massive and complex open source projects. Sources of data that are all tuned to readers fluent in a given language in a given domain. When an agent generates documentation in a project, it may draw upon that training data and skew toward language that’s domain-specific and overly technical—landing on jargon instead of plain language.
Not everyone will stumble over the same words. In my experience, however, people generally prefer plain, concise (not terse) language. But I had a realization during this pull request: comments are no longer just for people. Comments are now the source of truth for agents as well. Comments are context.
Good comments explain the why of code just as much if not more so than the what. “Stdlib JSON deserialization doesn’t work here, because the reflection costs us too much in performance.” They describe the invariants expected for the code to work. Without them, we are likely to revisit previous mistakes. Without them, agents are likely to make localized decisions based on structure lacking any of the context around intent.
The good news is that agents are responsive to instruction. A few lines in CLAUDE.md or your Cursor rules file is enough to meaningfully shift the output. And here’s the non-obvious part: plain language isn’t just easier for people to read; it’s better context for agents too. The same comment that helps a junior engineer understand intent helps an agent avoid making a locally-coherent edit that breaks things.
So here it is, my CLAUDE.md addition:
COMMENTS
* Use plain, direct language. Prefer common words over technical jargon unless the jargon is the subject matter.
* Explain why, not what, unless the what is genuinely non-obvious or these are comments exported for documentation.
* One idea per comment. If it needs more than two sentences, consider whether the code itself needs clarification instead.
* Match specificity to context: inline comments should be concrete and local; doc comments on public interfaces can be more precise.
* When editing code, update affected comments. Prefer deleting a comment over leaving one that is inaccurate or no longer relevant.
EXAMPLE
// Before (avoid this)
// evict traverses the corpus of cached entries and removes stale members
// whose TTL has been exceeded, maintaining the integrity of the cache
// and reclaiming memory allocated to expired corpus members.
func (c *Cache) evict() {
// After (prefer this)
// removes expired entries so stale data isn't served and memory doesn't grow unbounded
func (c *Cache) evict() {Comments only serve as reliable context if they’re accurate and current. An inaccurate comment that incorrectly describes what the code does or why is worse than no comment at all. It misleads the reader and, just as importantly, misleads the agent. Staleness is a related but separate problem: code changes and comments don’t always follow. Both are correctness issues. Reviewing comments for accuracy and relevance should be as routine as reviewing the code itself. When logic changes, the why and what must change with it.
So how do we optimize comments for people and agents? Understanding your audience is always part of writing. In this situation, it’s important to consider engineers of all skill levels and experience, the mental state of the person just paged in the middle of the night, as well as the agent making modifications to a critical segment of application logic. Fundamentally, this is how it has always been.
Self-documenting code as a substitute for comments is no longer defensible. As agents write more of our code, comments aren’t just helpful, they’re the primary mechanism for keeping humans in the loop. Context isn’t a nice-to-have. It’s how we stay in control.
