AI Misreads Your Code? Write Comments as an Interface, Not a Courtesy
Core conclusion: When a model reads code, the only intent information it can get—besides the syntax structure—is comments and naming. Naming can only express "what it is called"; comments can express "why it's written this way and what must not be changed." So key comments are not a courtesy for humans but an interface for the model—write the contract, pitfalls, and invariants, and the model won't treat a read-only function as a pure function, won't casually "optimize" away a branch with side effects, won't guess repeatedly when information is missing, and won't need to read three hundred lines to understand the design intent.
Table of Contents
- One-line conclusion
- When the model reads code, comments are the only intent signal
- Four typical failure modes
- Why comments are more effective than external docs
- What counts as a high-value comment
- Four comment templates you must write
- Symptom → cause → fix table
- A runnable comment audit script
- How to keep comments from rotting
- The cost math
- Boundaries: when not to write
1. One-Line Conclusion
Most AI-caused code errors aren't because it can't write, but because it misunderstood the intent of this piece of code. Intent isn't in the syntax—it's in the comments.
One sentence like "Must lock here, otherwise concurrent calls will double-charge" lets the model avoid an entire class of mistakes; one sentence like "Don't switch to batch query yet—this interface has ordering dependencies" saves three rounds of rework. Those two sentences cost about twenty tokens. The payoff is saving one review plus one rollback.
2. Comments as the Only Intent Channel
When a model gets a file, the information it can read has two layers:
- Structural layer: function names, parameter names, types, control flow. This layer tells it "what the code does."
- Textual layer: comments, docstrings, string constants. This layer is the only place that might tell it "why it does it this way."
The structural layer is precise, but the semantics are compressed. def fetch_user(uid) doesn't reveal whether it writes cache, throws exceptions, or is safe under concurrency—these are exactly the spots you trip over when changing code. Naming can help a little (fetch_user_cached is better than fetch_user), but once names get long, nobody wants to write them; comments have no such limit.
A metaphor: comments are handover notes. The person writing the note spends only two minutes, but it serves a receiver who comes on duty fresh every day, has zero memory of the project, and is especially fond of acting on their own—that receiver is the AI.
3. Four Failure Modes
- Misinterpreting function behavior:
fetch_userinternally writes cache and refreshes TTL. Without a comment, the model treats it as a pure query, so it calls it on a read-only path and the cache gets refreshed accidentally. Add one sentence: "This writes cache; usepeek_userfor read-only paths," and the accident disappears. - Over-optimization: there's an
if item in seenin a loop. The model sees a list lookup and switches it to aset—but it doesn't notice the loop body has order-sensitive log output. A comment "don't change to set; output order must match input" blocks it. - Over-thinking: a function has no boundary spec, so the model starts enumerating possibilities: what about empty input? duplicate keys? retry on failure? It either throws these questions back at you or invents its own assumptions. Write "input is already deduplicated by the caller; this function does not handle duplicates," and the guessing stops.
- Context bloat and forgetting: reading the whole 300-line implementation to understand "this section is for backward compatibility" squeezes out the earlier discussion context, and the model starts forgetting what you said three messages ago. Three lines of comment can replace that full read.
What's common to all four: it's not lack of knowledge—it's missing information.
4. Why Inline Beats Docs
- Proximity: the comment sits above the function; any model reading that function will read the comment. Design notes in a wiki aren't necessarily looked up, and may not be found at all.
- Co-evolution: whoever changes the code naturally updates the comment. External docs almost always go stale, and stale docs are worse than no docs—they give an authoritative-looking but wrong answer.
- Searchability: when the model greps for a function name, the comment gets pulled into context along with it; searching for a doc title may not hit.
- Low context cost: three lines of comments cost about 40 tokens, while reading a 300-line implementation costs ~4000 tokens. Replacing the latter with the former saves about 99% of your context budget.
In Put a README in every folder for AI to read first we covered the value of an "index layer": README solves "where to find", comments solve "how to understand once found." With both layers in place, the model doesn't have to guess.
5. What Counts as High-Value Comment
The only criterion: if this sentence weren't written, would someone (or the model) write it wrong? If yes, it's worth writing. If no, it's noise.
Four types of information are worth writing:
- Contract: input constraints, return-value meaning, whether exceptions are thrown, side effects, idempotency.
- Pitfall: places that look changeable but aren't, and what happens if you change them.
- Invariant: ordering dependencies, state preconditions, constraints that must be paired.
- Trade-off: why not use the simpler-looking alternative.
What not to write: paraphrasing the code (# set name to name), emotional complaints (# this is written badly), ownerless TODOs (# TODO optimize later, no owner and no date).
6. Four Comment Templates
Contract comment — above public functions, state inputs, returns, side effects:
def charge(order_id, amount_cents):
"""Charge and write a transaction record.
Args:
order_id: order number, must already exist and be unpaid
amount_cents: amount in integer cents, must be > 0
Returns:
transaction ID; repeated calls return the same transaction (idempotent)
Side effects:
Writes the orders table state, calls the payment gateway.
"""
Pitfall comment — right next to the dangerous line:
# Don't change to batch query: the three SQL statements have ordering dependencies,
# the second depends on the row lock from the first, and batch execution deadlocks
session.execute(insert_order)
session.execute(lock_order)
session.execute(update_balance)
Invariant comment — next to a state machine or cache:
# Invariant: every entry in cache must also be in db; the reverse may hold.
# So only "write db first, then cache" is allowed; the opposite leads to dangling cache
Trade-off comment — explains why the seemingly dumber approach was chosen:
# Linear scan instead of index: n is usually < 20,
# index overhead is higher than scan, measured ~3x slower
All four combined, a medium module needs roughly 15 to 25 comments. No need to chase coverage; only cover "places where something could be written wrong."
7. Symptom → Cause → Fix
| Symptom | Cause | Fix |
|---|---|---|
| AI treats a read-only function as a pure function | Side effects not stated | Add a "side effects" section in the contract comment |
| AI casually "optimizes" away a branch with side effects | Didn't say why it can't be changed | Pitfall comment states the consequence of changing |
| AI keeps asking about edge cases | Preconditions not written | Contract comment: "input already validated by caller" |
| AI only understands intent after reading the whole file | Missing global explanation | At module top, write 3 lines of design intent |
| AI changes one place and another breaks | Ordering dependencies not annotated | Invariant comment on the call chain |
| Comments rot within three months | No mechanism to keep them in sync | Same-PR rule + audit script |
8. Runnable Comment Audit
After writing comments, you still need to keep them from rotting. The script below checks four issues: public long functions missing a contract, paraphrasing comments, ownerless TODOs, and overly long comment blocks.
"""Comment audit: missing contract / paraphrasing / ownerless TODO / overly long block; exit code 1 on hit."""
import ast, pathlib, re, sys
INTENT = ("because", "avoid", "otherwise", "note", "must", "don't", "reason", "here", "why")
OWNER = re.compile(r"^(TODO|FIXME)\b(?!.*@)") # TODO followed by no @owner
NAME = re.compile(r"[A-Za-z_][A-Za-z_0-9]{2,}") # identifiers appearing in the comment
def public_long(node): # public function + body over 5 lines
return isinstance(node, ast.FunctionDef) and not node.name.startswith("_") and len(node.body) >= 5
def check_func(node): # missing contract: no params or return mention
if not isinstance(node, ast.FunctionDef): # function nodes only
return []
doc = ast.get_docstring(node) or ""
if public_long(node) and not ("Args" in doc or "Params" in doc):
return [(node.lineno, "missing contract", node.name)]
return []
def check_comment(lines, idx): # single-line comment check
text = lines[idx].strip().lstrip("#").strip()
nxt = lines[idx + 1].strip() if idx + 1 < len(lines) else ""
hits = []
if OWNER.search(text): # ownerless TODO
hits.append((idx + 1, "ownerless TODO", text[:26]))
shared = [n for n in NAME.findall(text) if n in nxt] # comment noun repeats on next line
if shared and not any(w in text for w in INTENT):
hits.append((idx + 1, "paraphrasing comment", text[:26]))
return hits
def check_block(lines, start): # consecutive comment block >6 lines without intent word
end = start
while end < len(lines) and lines[end].strip().startswith("#"):
end += 1
block = "".join(lines[start:end])
if end - start >= 6 and not any(w in block for w in INTENT):
return [(start + 1, "overly long block", f"{end - start} lines without intent")]
return []
def main(root): # aggregate and decide exit code
files = sorted(pathlib.Path(root).rglob("*.py"))
total = 0
for path in files:
src = path.read_text(encoding="utf-8")
lines = src.splitlines()
hits = []
for node in ast.walk(ast.parse(src)): # check each function for contract
hits += check_func(node)
walked = set()
for idx, line in enumerate(lines): # check each comment line
if not line.strip().startswith("#") or idx in walked:
continue
is_block = idx + 1 < len(lines) and lines[idx + 1].strip().startswith("#")
if is_block:
hits += check_block(lines, idx)
walked |= set(range(idx, idx + 6))
else:
hits += check_comment(lines, idx)
for lineno, kind, detail in sorted(hits):
print(f"{path.as_posix()}:{lineno} [{kind}] {detail}")
total += len(hits)
print(f"\nscanned {len(files)} files, {total} comment issues")
return 1 if total else 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "."))
Run it on three small files with python comment_audit.py app (billing.py has a five-line public function without a contract, sync.py has a paraphrasing comment and an ownerless TODO, cache.py has a six-line "leave it alone" block). Actual output:
app/billing.py:1 [missing contract] apply_discount
app/cache.py:1 [overly long block] 6 lines without intent
app/sync.py:1 [paraphrasing comment] read batch to queue
app/sync.py:8 [ownerless TODO] TODO add timeout later
scanned 3 files, 4 comment issues
Exit code 1, so a CI run fails. Swap in a cleaned directory where contracts are filled and "don't touch this" becomes "amount must be integer cents, otherwise float accumulation drifts 0.01", and the output says "scanned 1 file, 0 comment issues" with exit code 0.
Limitations are stated plainly: the paraphrasing detection relies on a heuristic (does the comment's noun reappear on the next line), so it both false-positives and misses. Its real value is putting "does this comment carry new information" on the table for a human to judge.
9. Keeping Comments Alive
- Same-PR rule: changing function behavior requires updating its contract comment in the same PR; treat "behavior changed, comment didn't" as a blocking review item.
- Prefer assertions over comments when possible: ordering dependencies can become runtime asserts; edge conditions can become test cases. Comments explain; asserts enforce.
- Treat comments as a supplement to tests: if you can't write a clear contract, that often means the function has too many responsibilities—a refactoring signal, not a writing problem.
- Use the audit script to guard the floor: at minimum, keep "public functions have contracts" and "no ownerless TODOs" from regressing.
In When a project gets messy, don't rush to change the architecture we discussed measuring before acting. Comment hygiene is the same: run an audit first to get a list of issues, then decide which functions to fix. Don't start rewriting from the first file.
10. The Math
One contract comment costs about 40 tokens. Assume without it the model treats a "cache-writing query" as a pure function, the change is caught later, and you need an extra review round plus a fix round, each round about 2000 tokens of context:
$6000 / 40 = 150$
A one-time 40-token investment saves 6000 tokens of rework, a roughly 150x ratio. Scale to 20 key functions: the one-time cost is about 800 tokens, less than the cost of the model reading one medium file once.
What's truly expensive isn't the length of the comment—it's the part where the model fills the gap by guessing. Wrong guesses require rework; even correct guesses cost extra confirmation rounds.
11. Boundaries
- No comments on trivial code:
# iterate over listis noise and may even make the model suspect hidden meaning. - Auto-generated API docs don't replace contract comments: they derive from types and can't infer side effects or ordering dependencies.
- Comments don't replace types: constraints expressible as types belong in types, because type checkers enforce them.
- No novels: a single comment over five lines usually means the logic should be split out, not explained further.
One-line judgment: If this comment were deleted, would the model or a newcomer write something wrong? If yes, keep it; if no, cut it. Precision beats volume every time.
This column, "AI Development Paradigm," focuses on code organization, review, and engineering constraints under AI collaboration—covering directory structure, comment conventions, type design, and CI gates. Each post includes a runnable check script and publishes weekly. To read in order, subscribe on the column page.
Top 1 of 2 from juejin.cn, machine-translated. The original thread is authoritative.
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.