20 个 token 的注释,可能替一次代码审查和一次线上回滚买单。我们注意到,AI 编程的下一道门槛不是模型会不会写代码,而是开发者能否把“为什么这样写”清楚地留在代码里。

这是什么

源代码通常只告诉 AI“做了什么”,很少说明“为什么不能换一种做法”。注释和文档字符串(写在代码或函数旁、用于解释用途的文本)则承载了意图:函数是否有副作用、调用顺序是否固定、哪些看似低效的写法必须保留。

文章列出的四类高价值注释分别是:契约,说明入参、返回值与副作用;陷阱,指出看似可以优化、实际不能改的地方;不变量,记录必须持续成立的约束;取舍,解释为何采用复杂方案。判断标准也很直接:如果缺少这句话,人或模型可能写错,就值得写;只是复述代码,则没有必要。

与放在 Wiki 或 README 中的说明相比,行内注释离代码更近,也更容易随着代码一起被 AI 读取。文章估算,三行注释约需 40 个 token,而通读 300 行实现可能消耗约 4000 个 token。不过,这只是特定示例下的估算,不代表所有项目都能获得同等比例的效率提升。

行业怎么看

我们的判断是,这把 AI 编程从“更聪明的自动补全”推向“更可靠的工程协作”。当代码生成能力逐步接近,开发团队真正的差异会落在上下文质量上:谁能持续提供准确、可维护的意图说明,谁就更少面对模型自作主张后的返工。

但风险同样明确。第一,注释一旦过期,会给模型一个看似权威的错误答案,甚至比没有注释更危险;只靠开发者自觉,无法保证长期质量。第二,过度注释可能制造新的噪音,若团队把所有设计文档都塞进函数旁,模型仍会被大量无关信息干扰。第三,这类收益高度依赖代码库、任务和模型能力,不能把个别案例中的 token 节省直接当成普遍回报。

因此,文章提出让注释与代码进入同一次代码审查,并通过脚本检查,是比“要求大家多写注释”更可靠的方向。不过,静态脚本只能发现缺少说明,无法判断说明是否真实、是否已经过时,最终仍需要代码所有者承担责任。

对普通人的影响

对企业 IT:企业可把关键注释纳入代码规范与审查流程,优先覆盖支付、权限、缓存和状态机等高风险模块,而不是追求注释数量。

对个人职场:使用 AI 编程工具的开发者会受益于更清晰的任务说明;团队协作中,写出边界与约束,可能比反复调整提示词更省时间。

对消费市场:短期看,用户未必感知到 AI 编程因此“更聪明”;但代码质量和交付稳定性改善后,AI 生成功能的故障率、迭代速度及产品体验可能随之变化。