AI Misreads Your Code? Write Comments as an Interface, Not a Courtesy
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.
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.
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.
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.
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.