跪拜 Guibai
← Back to the summary

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

  1. One-line conclusion
  2. When the model reads code, comments are the only intent signal
  3. Four typical failure modes
  4. Why comments are more effective than external docs
  5. What counts as a high-value comment
  6. Four comment templates you must write
  7. Symptom → cause → fix table
  8. A runnable comment audit script
  9. How to keep comments from rotting
  10. The cost math
  11. 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:

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

What's common to all four: it's not lack of knowledge—it's missing information.

4. Why Inline Beats Docs

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:

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

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

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.

Comments

Top 1 of 2 from juejin.cn, machine-translated. The original thread is authoritative.

樊小肆 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.