Wink Pings

代码注释,正在欺骗你的 AI

Matt Pocock 提出一个让 AI 分类删除代码注释的方法:同义反复、借口、过时、决策记录,最后用 lint 规则全面禁止。评论区补充了第五类“断言”,还有人已经写好了插件。

AI 编程时代,代码注释不再只是给人看。AI agent 会读它们,然后当作事实。Matt Pocock 今天抛出一个长 prompt,直接对代码注释下手。

他让 AI 审查仓库里的每一条注释,分成四类:

  • 同义反复:只是把代码本身说了一遍
  • 借口:让一个 hack 实现看起来合理,然后四处传播
  • 过时:引用的代码或实现早已不存在
  • 决策记录:记录了一个重要但不显而易见的决定

处理方式也简单:同义反复和过时注释直接删;借口注释删掉,并给那个 hack 实现记一个 issue;决策记录移进 ADR(架构决策记录)。最后,创建一条 lint 规则禁止注释,再弄一个 /delete-comment 技能,方便以后重复清理。他还让 AI 估算,删光注释能少多少行代码。

评论区很快补充了不少细节。

有人加了一个第五类:断言。它描述代码运行时的行为,可能从写下的第一天就是错的。处理办法是先转成测试,再删注释。有开发者在自己代码里抓到一个例子:一条“holder rolled back, retry”注释,下面走的路径真实 Postgres 根本不会走,测试一跑就暴露了。

也有人已经把这套东西做成了 oxlint 插件。规则只放行几种特殊注释:VENDOR(绕别人软件的缺陷)、SAFETY(类型断言上方)、BRIDGE(Effect 到 Promise 桥接)、QUARANTINE(跳过的测试),其余全删。工具指令和纯 JS 文件里的 JSDoc 类型标签留着。

反对意见也有。ADR 本身也会腐烂。有开发者说,代码里最好留一行指向 ADR 的指针,否则下一个 agent 根本找不到。公共 API 的文档字符串是否豁免,也有人问了。Matt 在另一条回复里亮明立场:所有注释。

过时注释对 AI 的伤害比对人大。人看到注释和代码不一致,会去查证。AI 会直接相信注释,然后在错误的基础上继续建东西。评论区有人形容:agent 写的注释会毒化上下文。

有开发者晒出截图,说他今天也构建了同样的技能。

Zebro 的截图

另一条回复推荐了一个工具 cccc,用来测量代码的认知复杂度和圈复杂度。它用 Rust 写,单二进制,支持 TypeScript、Rust、Go、PHP、Ruby 等近二十种语言。跑 zod 整个 src,286 个 TS 文件,6.8 万行,只要 15 毫秒,内存 12.5 MB。对比之下,ESLint 加 SonarJS 跑同样的指标要 1.8 秒,内存 604 MB。推荐者用它来让 AI 评估哪些测试可以被删除。

Matt 给这条 prompt 配的话是:I'm sold. Comments considered harmful.

这句话放在两年前会被当成段子。现在,它更像一个工程决策。

代码注释不会消失。但在 AI 读代码的时代,它从给人看的说明书,变成了给模型喂的上下文。写注释成了一件需要克制的事。如果你非要写注释,把它写成测试。

发布时间: 2026-11-21 00:33