核心结论:模型读代码时,除了语法结构,唯一能拿到的「意图信息」就是注释和命名。命名只能承载「它叫什么」,注释才能承载「为什么这么写、不能怎么改」。所以关键注释不是给人看的礼貌,而是给模型看的接口------写清契约、陷阱、不变量,模型就不会把只读函数当纯函数改、不会顺手「优化」掉有副作用的分支、不会在缺信息时反复猜测,也不用通读三百行才明白设计意图。
目录
- 一句话结论
- 模型读代码时,注释是唯一的意图信号
- 四种典型事故
- 为什么注释比外部文档更有效
- 什么才算高价值注释
- 四类必写注释与模板
- 症状 → 原因 → 解法对照表
- 可直接运行的注释体检脚本
- 怎么让注释不腐烂
- 这笔账怎么算
- 边界:什么时候不用写
1. 一句话结论(The One-Line Conclusion)
AI 改代码出错的多数场景,不是它不会写,而是它理解错了这段代码的意图。而意图不在语法里,在注释里。
一句「这里必须加锁,否则并发下会重复扣款」,能让模型避开一整类错误;一句「先别改成批量查询,这个接口有顺序依赖」,能省掉三轮返工。这两句话的成本是二十来个 token,收益是省下一次 review 加一次回滚。
2. 模型读代码时,注释是唯一的意图信号(Comments as the Only Intent Channel)
模型拿到一个文件时,能读到的信息分两层:
- 结构层:函数名、参数名、类型、控制流。这一层告诉它「代码在做什么」。
- 文本层:注释、docstring、字符串常量。这一层才可能告诉它「为什么这么做」。
结构层是精确的,但语义是压缩的。def fetch_user(uid) 读不出它会不会写缓存、会不会抛异常、并发下安不安全------这些恰好是改代码时最容易踩的地方。命名能补一点(fetch_user_cached 好过 fetch_user),但命名一长就没人愿意写,注释没有这个限制。
打个比方:注释是交接便条。写便条的人只花两分钟,但它服务的对象是一个每天新上岗、对项目零记忆、还特别爱自作主张的接手者------AI 就是这个接手者。
3. 四种典型事故(Four Failure Modes)
- 曲解功能 :
fetch_user内部其实会写缓存并刷新 TTL。没有注释,模型认为它是纯查询,于是在只读路径里放心调用,缓存被意外刷新。加上一句「会写缓存,只读路径请用peek_user」,事故消失。 - 过度优化 :循环里有一句
if item in seen。模型看到是列表查找,顺手改成set------但它没注意循环体内部有顺序敏感的日志输出。一句「不要换 set,输出顺序要与输入一致」就能拦住。 - 过度思考:函数没有边界说明,模型开始罗列各种可能:空输入怎么办、重复 key 怎么办、失败要不要重试。它会把这些问题抛回给你,或者自己编一套假设。写上「入参已由上层去重,本函数不处理重复」,猜测立刻停止。
- 上下文膨胀与遗忘:读完整个 300 行实现才明白「这段是兼容旧版本」,而这三百行已经挤掉了前面讨论的需求上下文,模型开始忘掉你三条消息前说过的话。三行注释能替代这次通读。
四种事故的共同点:都不是知识不足,是信息缺失。
4. 为什么注释比外部文档更有效(Why Inline Beats Docs)
- 就近(Proximity):注释在函数上方,模型读这个函数必然读到它。放在 wiki 里的设计说明,模型不一定会去找,也可能找不到。
- 同步演进:改代码的人顺手就改了注释;外部文档几乎必然过期,而过期的文档比没有文档更糟------它会给出一个看起来很权威的错误信息。
- 可检索:模型用 grep 定位函数名时,注释会一起被拉进上下文;搜文档标题则未必能命中。
- 上下文成本低:三行注释约 40 token,通读三百行实现约 4000 token。用前者替代后者,等于把上下文预算省下 99%。
在每个文件夹都放一份 README 让 AI 先读里我们讲过「索引层」的价值:README 解决「去哪里找」,注释解决「找到之后怎么理解」。两层都补齐,模型才不需要靠猜。
5. 什么才算高价值注释(What Counts as High-Value)
判断标准只有一条:这句话如果不写,别人(或模型)会不会写错。会,就值得写;不会,就是噪音。
值得写的信息有四类:
- 契约(Contract):入参约束、返回值含义、是否会抛异常、有没有副作用、是否幂等。
- 陷阱(Pitfall):看着能改、其实不能改的地方,以及改了会发生什么。
- 不变量(Invariant):顺序依赖、状态前置条件、必须成对调用的约束。
- 取舍(Trade-off):为什么不用那个更简单的写法。
不该写的:复述代码(# 设置 name 为 name)、情绪吐槽(# 这里写得烂)、无主 TODO(# TODO 以后优化,没有负责人没有日期)。
6. 四类必写注释与模板(Four Templates)
契约注释------公共函数的上方,写清入参、返回、副作用:
python
def charge(order_id, amount_cents):
"""扣款并写流水。
参数:
order_id: 订单号,必须已存在且未支付
amount_cents: 金额,整数分,必须大于 0
返回:
流水号;重复调用返回同一条流水(幂等)
副作用:
写 orders 表状态,调用支付网关
"""
陷阱注释------贴着那行危险代码:
python
# 不要改成批量查询:这三条 SQL 之间有顺序依赖,
# 第二条依赖第一条插入的行锁,批量执行会死锁
session.execute(insert_order)
session.execute(lock_order)
session.execute(update_balance)
不变量注释------写在状态机或缓存旁边:
python
# 不变量:cache 里的条目一定也在 db 里,允许反向缺失。
# 因此只允许「先写 db 再写 cache」,反过来会出现缓存指空
取舍注释------解释为什么选了这个看起来更笨的写法:
python
# 这里用线性扫描而不是建索引:n 通常小于 20,
# 建索引的固定开销比扫描还高,实测约 3 倍慢
四类加起来,一个中等模块大约需要 15 到 25 条注释,不追求覆盖率,只覆盖「会写错的地方」。
7. 症状 → 原因 → 解法对照表(Symptom-Cause-Fix)
| 症状 | 原因 | 解法 |
|---|---|---|
| AI 把只读函数当纯函数用 | 副作用没写出来 | 契约注释补「副作用」段 |
| AI 顺手「优化」掉有副作用的分支 | 没说明为什么不能改 | 陷阱注释写清改动后果 |
| AI 反复追问边界情况 | 没写前置条件 | 契约注释写「入参已由上层校验」 |
| AI 读完整个文件才明白意图 | 缺全局说明 | 模块顶部写 3 行设计意图 |
| AI 改完一处,另一处跟着错 | 顺序依赖没标注 | 不变量注释贴在调用链上 |
| 注释写完三个月就失效 | 没有和代码同改的机制 | 注释与代码同 PR + 体检脚本 |
8. 可直接运行的注释体检脚本(Runnable Comment Audit)
写完注释还得防它腐烂。下面这段脚本查四类问题:公共长函数缺契约、复述型注释、无主 TODO、超长注释块。
python
"""注释体检:缺契约注释 / 复述型注释 / 无主 TODO / 超长注释块,命中即退出码 1。"""
import ast, pathlib, re, sys
INTENT = ("因为", "避免", "否则", "注意", "必须", "不要", "原因", "这里", "why")
OWNER = re.compile(r"^(TODO|FIXME)\b(?!.*@)") # TODO 后面没有 @负责人
NAME = re.compile(r"[A-Za-z_][A-Za-z_0-9]{2,}") # 注释里出现的标识符
def public_long(node): # 公共函数 + 超过 5 行正文
return isinstance(node, ast.FunctionDef) and not node.name.startswith("_") and len(node.body) >= 5
def check_func(node): # 缺契约:没有参数或返回说明
if not isinstance(node, ast.FunctionDef): # 只处理函数节点
return []
doc = ast.get_docstring(node) or ""
if public_long(node) and not ("参数" in doc or "Args" in doc):
return [(node.lineno, "缺契约注释", node.name)]
return []
def check_comment(lines, idx): # 单行注释判定
text = lines[idx].strip().lstrip("#").strip()
nxt = lines[idx + 1].strip() if idx + 1 < len(lines) else ""
hits = []
if OWNER.search(text): # 无主 TODO
hits.append((idx + 1, "无主TODO", text[:26]))
shared = [n for n in NAME.findall(text) if n in nxt] # 注释名词在下一行复现
if shared and not any(w in text for w in INTENT):
hits.append((idx + 1, "复述型注释", text[:26]))
return hits
def check_block(lines, start): # 连续注释块超 6 行且无意图词
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, "超长注释块", f"{end - start} 行无意图说明")]
return []
def main(root): # 汇总并决定退出码
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)): # 逐个函数查契约
hits += check_func(node)
walked = set()
for idx, line in enumerate(lines): # 逐行查注释
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"\n扫描 {len(files)} 个文件,注释问题 {total} 处")
return 1 if total else 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "."))
拿三个小文件跑 python comment_audit.py app(billing.py 有个五行的公共函数没写契约,sync.py 有一句复述型注释和一个无主 TODO,cache.py 有六行「先这样、别动」的注释块),实际输出是:
text
app/billing.py:1 [缺契约注释] apply_discount
app/cache.py:1 [超长注释块] 6 行无意图说明
app/sync.py:1 [复述型注释] 读取 batch 到 queue
app/sync.py:8 [无主TODO] TODO 之后加超时
扫描 3 个文件,注释问题 4 处
退出码 1,挂进 CI 就是一次失败。换成补好契约注释、把「别动这块」改成「金额必须用整数分,否则浮点累加会漂移 0.01」的干净目录,输出「扫描 1 个文件,注释问题 0 处」,退出码 0。
局限说清楚:复述型判定靠「注释名词是否在下一行复现」这个启发式,会误报也会漏报;它真正的价值是把「这条注释有没有携带新信息」摆到台面上让人判断。
9. 怎么让注释不腐烂(Keeping Comments Alive)
- 同 PR 规则:改函数行为就必须同期改它的契约注释,review 时把「行为变了、注释没变」当成阻塞项。
- 能写成断言就别只写注释:顺序依赖可以加成运行时断言,边界条件可以写成测试用例。注释负责解释,断言负责强制。
- 把注释当测试的补充:写不清契约,往往说明函数本身职责过多------这是重构信号,不是写作问题。
- 用体检脚本守住下限:至少保证「公共函数有契约」「没有无主 TODO」这两条不退化。
在项目越写越乱别急着改架构里我们讲过先量化再动手:注释治理同理,先跑一次体检拿到问题清单,再决定补哪几个函数,别从第一个文件开始重写。
10. 这笔账怎么算(The Math)
一条契约注释大约 40 token。假设没有它,模型把「会写缓存的查询」当成纯函数,改完之后被发现,于是多一轮 review、一轮修正,每轮上下文约 2000 token:
6000/40=150
一次性投入 40 token,省掉 6000 token 的返工,比值约 150 倍。把范围放大到 20 个关键函数,一次性成本约 800 token,少于模型读一遍单个中型文件的开销。
真正贵的不是注释的字数,是 模型靠猜填补空白 的那部分------猜错要返工,猜对也要多花几轮确认。
11. 边界:什么时候不用写(Boundaries)
- 显而易见的代码不写:
# 遍历列表这类注释只是噪音,还会让模型误以为这里有隐藏含义。 - 自动生成的接口文档不替代契约注释:它们从类型推导,推导不出副作用和顺序依赖。
- 注释不能替代类型:能用类型表达的约束,优先写类型,类型能被检查器强制。
- 不要写长篇小说:单条注释超过五行,通常说明该把逻辑拆出去,而不是继续解释。
一句话判断:这段注释删掉之后,模型或新人会不会写错。会,就留着;不会,就删------写得准永远比写得多值钱。
本专栏《AI 开发范式》聚焦 AI 协作下的代码组织、代码评审与工程约束,从目录结构、注释规范一直讲到类型设计与 CI 门禁,每篇都配一段可直接运行的检查脚本,每周更新一篇。想按顺序读完,可在专栏页订阅。