为什么 AI 生成的注释腐烂得比代码还快

当智能体（agent）在同一个 diff 中编写函数和注释时，该注释并不是文档。它是代码在编写时的转述，由同一个模型从同一个上下文中生成。当代码第一次发生变动时，它就会悄然出错。函数被重构，参数类型改变，或者添加了提前返回（early-return），但注释却保持不变。到下个季度，注释所编码的规范已不再与代码匹配，而下一位读者会因为注释更易读而选择相信它。

这是一个古老的失效模式 —— 人类修改代码，注释保持陈旧 —— 但智能体从三个维度同时加速了这一进程。注释量增加了，因为智能体无论是否需要，都会给每个函数添加文档块（doc block）。注释的语法非常完美，所以审阅者不会将其标记为低质量。而且，注释用与代码实际执行不同的术语来转述代码，因此它们看起来像文档，但实际上编码了第二套规范，这套规范独立于第一套规范而漂移。

代价在后期显现，表现为一个不断累积的维护陷阱。未来的读者根据注释构建心理模型。当两者出现分歧时，未来的智能体 —— 或未来的工程师 —— 会“修复”代码以匹配注释。最终交付的 bug 并非幻觉，而是对错误规范的忠实执行。

第二规范问题

转述其上方函数的代码注释是第二套规范。函数在代码中表达一个意思；注释用英语表达一个与之相近的意思。只要两者是由同一位作者在同一时刻编写的，它们就是一致的。代码一旦变动，它们就会产生分歧，并且没有任何机制能让它们再次达成一致。

对于人类编写的注释，这个问题会自我限制。人类懒于写注释，所以存在的注释往往编码了作者认为值得表达的内容 —— 一个不变式（invariant）、一个变通方法（workaround）或一个非显而易见的原因。这些内容仍然容易发生漂移，但总量较小，且幸存的注释通常编码了关键信息，细心的审阅者在周围代码变动时会注意到这些信息。

智能体没有这种过滤器。一个智能体会很乐意写一段四行的 docstring 来描述一个三行的函数。docstring 重新表述了参数名、返回类型以及显而易见的事实。在第一天，这些都没有错。在第一天，这些也都没有用。但其中的每一行都是对未来的“人质”：当函数改变时，docstring 中的每个子句都有可能出错。在经过两次重构后，整个注释块仍然准确的概率趋近于零，而且由于注释读起来依然流畅，没人会注意到这一点。

这种不对称性正是其危险所在。崩溃的 AI 生成代码往往会产生响亮的动静 —— 类型错误、测试失败、预发环境（staging）出现 500。而发生漂移的 AI 生成注释则是悄然崩溃的。当 docstring 撒谎时，没有测试会失败。当正文说“缺失键时返回 null”而代码现在抛出异常时，没有编译器会发出警告。注释的腐烂是不可见的，直到读者据此采取行动。

为什么审阅者会放过这些注释

在 2025 年的一篇关于 Copilot 代码审查的 GitHub 博客文章中，团队注意到智能体现在每次审查平均产生约 5.1 条评论，并在 29% 的 PR 中完全保持沉默 —— 这是为了减少噪音，使高信号的反馈得以保留而进行的明确努力的结果。此时，审阅方的纪律已经得到了很好的理解：当 AI 审查评论的操作率低于 30–40% 时，你就是在产生噪音，配置需要收紧。

但同样的纪律很少应用于 diff 内部 AI 生成的 docstrings 和行内注释。原因有两个。

第一，注释不会破坏构建（build）。审阅者在扫描一个 400 行的 PR 以寻找问题时，关注的是签名、控制流、错误处理以及显而易见的出错点。辅助函数上一个语法整洁的 docstring 在视觉上是绿灯 —— 它看起来像是作者足够细心地进行了记录。审阅者的模式匹配器将其视为积极信号并继续前进。

第二，这些注释整齐划一地流畅。人类编写的注释风格多样，反映了作者与代码的关系：对自己编写并信任的代码言简意赅，对令其紧张的代码充满防御性，对令其惊讶的代码长篇大论。智能体编写的注释风格统一且考究，语法统一且完整，并且统一使用中性的文档语气。没有语气信号能提示这条注释是否比下一条更关键。因此，审阅者要么全部信任它们（常见情况），要么全部不信任（罕见且令人疲惫）。

流畅性差距就是陷阱。一个会拒绝 "ok now we add the user" 这种注释的审阅者，却不会拒绝 "Adds the user to the database after validating the email and normalizing the username for case-insensitive lookup."。第二句话并不比第一句话更经过验证。它只是格式更好。

复合维护陷阱

注释第一次与代码发生偏离时，成本很小 —— 一个困惑的读者，损失几分钟时间。复合成本则发生在更远的一个周期，即这种偏离开始影响未来的修改时。

加载中…