AI 读不懂你的代码怎么办:用高价值注释消除曲解、过度优化与上下文膨胀

核心结论:模型读代码时,除了语法结构,唯一能拿到的「意图信息」就是注释和命名。命名只能承载「它叫什么」,注释才能承载「为什么这么写、不能怎么改」。所以关键注释不是给人看的礼貌,而是给模型看的接口------写清契约、陷阱、不变量,模型就不会把只读函数当纯函数改、不会顺手「优化」掉有副作用的分支、不会在缺信息时反复猜测,也不用通读三百行才明白设计意图。

目录

  1. 一句话结论
  2. 模型读代码时,注释是唯一的意图信号
  3. 四种典型事故
  4. 为什么注释比外部文档更有效
  5. 什么才算高价值注释
  6. 四类必写注释与模板
  7. 症状 → 原因 → 解法对照表
  8. 可直接运行的注释体检脚本
  9. 怎么让注释不腐烂
  10. 这笔账怎么算
  11. 边界:什么时候不用写

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=1506000 / 40 = 150 6000/40=150

一次性投入 40 token,省掉 6000 token 的返工,比值约 150 倍。把范围放大到 20 个关键函数,一次性成本约 800 token,少于模型读一遍单个中型文件的开销。

真正贵的不是注释的字数,是 模型靠猜填补空白 的那部分------猜错要返工,猜对也要多花几轮确认。

11. 边界:什么时候不用写(Boundaries)

  • 显而易见的代码不写:# 遍历列表 这类注释只是噪音,还会让模型误以为这里有隐藏含义。
  • 自动生成的接口文档不替代契约注释:它们从类型推导,推导不出副作用和顺序依赖。
  • 注释不能替代类型:能用类型表达的约束,优先写类型,类型能被检查器强制。
  • 不要写长篇小说:单条注释超过五行,通常说明该把逻辑拆出去,而不是继续解释。

一句话判断:这段注释删掉之后,模型或新人会不会写错。会,就留着;不会,就删------写得准永远比写得多值钱。

本专栏《AI 开发范式》聚焦 AI 协作下的代码组织、代码评审与工程约束,从目录结构、注释规范一直讲到类型设计与 CI 门禁,每篇都配一段可直接运行的检查脚本,每周更新一篇。想按顺序读完,可在专栏页订阅。

相关推荐
ZhengEnCi1 小时前
AI 总模仿代码库里的过时写法怎么办:先清坏样例,再用类型与测试让 AI 无法犯错
人工智能·ai编程
Flynt3 小时前
Chrome给AI编程助手塞了203篇前端规范,我拆包实测:检索0.77秒是真快,扫描器有点挑食
前端·chrome·ai编程
爱查宝小二3 小时前
爱查宝降AIGC效果实测与过检能力展示
aigc
ServBay3 小时前
Local harness 将退役,VS Code 本地开发要不要搬到云端?
后端·ai编程·visual studio code
花椒技术4 小时前
从“实时生成游戏”出发,我们用 AI 做了四次游戏开发尝试
人工智能·aigc·游戏开发
T_Wizard4 小时前
AI 回复为什么要转圈 3 秒才「啪」一下全出来?把流式输出拆开看,顺便踩了 6 个坑
java·ai编程
0zien04 小时前
【AI编程 - 第二弹】宝石TD
ai编程
IT规划师5 小时前
热点速递 | 未来软件工程六大战略技术趋势
ai编程
qinglongcn5 小时前
怎么让 200 轮的长任务不崩——三层保全策略
agent·ai编程