跪拜 Guibai
← All articles
AI Programming · AIGC

AI Misreads Your Code? Write Comments as an Interface, Not a Courtesy

By ENCI ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Teams that feed AI uncommented code pay in rework: a missing side-effect note turns a read path into a cache-mutating bug, and a misplaced "optimization" breaks ordering. Writing 40 tokens of intent saves roughly 150x that in wasted context and review cycles, so comment hygiene becomes a direct cost lever for any team shipping AI-assisted changes.

Summary

When a model reads your code, it gets two layers: structure (names, types, control flow) and text (comments, docstrings). Only the text layer can say why something is written a certain way. Naming can only say what a thing is called; comments carry the "don't change this or the cache breaks" information that prevents the model from guessing and making expensive mistakes. The article lays out four failure modes—misinterpretation, over-optimization, over-thinking about boundaries, and context bloat that drowns earlier instructions—and shows each one is caused by missing intent, not lack of model knowledge.

High-value comments are judged by one test: if you delete it, will the model or a newcomer write wrong code? If yes, write it. Four types are worth writing: contract (inputs, returns, side effects), pitfall (what looks changeable but isn't), invariant (ordering or state preconditions), and trade-off (why the obvious approach was rejected). A medium module needs about 15 to 25 such comments. The article includes a runnable Python audit script that flags common failures—public functions without a contract, paraphrasing comments, ownerless TODOs, and overly long comment blocks without intent—and exits 1 so it can gate CI. It also suggests a same-PR rule to keep comments alive and argues that unclear contracts are often a refactoring signal.

The cost argument is blunt: one 40-token contract comment can save 6000 tokens of rework and review context, a 150x return. The boundaries section clarifies when not to write comments: trivial code, auto-generated docs that can't capture side effects, and anything that could be expressed as a type or assertion. The core reframing is that comments are an interface for an AI reader, not documentation for humans.

Takeaways
— A model reads two layers in a file: structure (names, types, control flow) and text (comments, docstrings); only text carries why, so comments are the only intent channel beyond naming.
— Four failure modes from missing intent: misinterpreting function behavior, over-optimizing away side effects, over-thinking boundary conditions, and context bloat that drowns earlier instructions.
— Inline comments beat external docs because they sit next to the code, co-evolve in the same pull request, get pulled into context during grep, and cost ~40 tokens versus ~4000 to read a 300-line implementation.
— The high-value comment test: if deleting it causes an AI or newcomer to write wrong code, it's worth writing; otherwise it's noise.
— Four comment templates: contract, pitfall, invariant, and trade-off. A medium module needs 15 to 25 of these, covering only spots where something could be written wrong.
— A runnable Python audit script flags public long functions missing a contract, paraphrasing comments, ownerless TODOs, and comment blocks over 6 lines without an intent word; it returns exit code 1 so it can fail CI.
— Keep comments alive with a same-PR rule, prefer assertions and tests over comments when possible, and treat an unclear contract as a refactoring signal.
— Cost math: one 40-token contract comment can save about 6000 tokens of rework and review rounds, a 150x return; scaling to 20 key functions costs ~800 tokens total.
— Don't write comments on trivial code, auto-generated API docs don't substitute for contract comments, types beat comments for enforceable constraints, and a single comment over five lines usually indicates the logic should be split.
Conclusions

The core reframing is that comments are an interface for an AI reader, not documentation for humans. That flips the usual priority: you write comments where the model is likely to guess, not where a human might forget.

The cost math is crude but directionally sound: context is the scarcest resource in LLM-assisted coding, so a few lines of intent that eliminate guessing pay off disproportionately compared to reading the full implementation.

The audit script's paraphrase detection is a heuristic and the author admits it false-positives and misses. That's an honest acknowledgment that judging 'does this comment carry new information' is a human skill, not yet a toolable one.

Concepts & terms
Contract comment
A comment on a public function that states input constraints, return semantics, side effects, and idempotency—the information that doesn't appear in the signature or type.
Pitfall comment
A comment placed next to code that looks safely changeable but isn't, explaining what will break if modified, to prevent the AI or a human from "optimizing" it.
Invariant comment
A comment that states a property that must always hold, such as ordering dependencies or state preconditions, so the model doesn't reorder operations or break paired calls.
Trade-off comment
A comment that explains why a deliberately simpler or less obvious implementation was chosen, preventing the AI from "improving" it into something worse.
Context budget
The limited window of tokens a language model can attend to during a conversation; comments that encode intent in a few tokens free up that budget for the actual task instead of forcing the model to read long implementations.
From the discussion
Featured comments
樊小肆 1 likes

It will itself discover and point out: your comment says xxx, but the actual code is xxxx. Relying solely on comments is not intelligence—it becomes idiocy.

ENCI

You hit the nail on the head 🙂 When comments and code conflict, if AI trusts the comments, it executes the errors with more confidence, worse than not having comments at all. The article takes the same stance: outdated documentation is worse than none, so the last section says 'if you can write an assertion, don't just write a comment'—order dependencies and boundary conditions go to runtime assertions and tests, and comments only explain why. The truly intelligent approach is to have AI report the inconsistency between comments and code as drift and ask you, rather than modify the code according to the comments.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗