用 AI 写注释比用 AI 写代码更值
约 3 分钟0 阅读
有个祖传模块，一直没人敢动。
代码是几年前某位离职同事写的，逻辑复杂，没注释，没文档。每次有新人来，都得花一两周才能大致看懂。我接手维护它的那阵子，自己也只是「勉强能改」，不敢深动。
有一天我突发奇想，把这个模块的源码整个喂给 AI，让它写注释和文档。没指望它多准，想着有个大概也比没有强。
结果出乎意料。
注释让模块「活了」过来
AI 生成的注释和文档，我逐个读过去核对。大部分准确，少数几处它理解偏了，我改过来。
改完的版本推给团队，后面接手这个模块的新人，上手时间从两周缩到三四天。一个没人敢碰的祖传模块，因为有了注释，变得能交接了。
这次之后我琢磨了半天：为什么这件「小事」效果这么明显？
注释的 ROI 比代码高
想来想去，我发现让 AI 写注释，比让它写代码划算得多。
从价值看：一段新代码，AI 写了���后你还得读、改、测、调，省的是打字的时间，但打字本来不是瓶颈。而一段没注释的旧代码，有了注释，省的是后面所有人理解它的时间——这个时间，是成倍放大的。AI 写代码省一个人的几次，AI 写注释省所有未来读者的无数次。
从风险看：AI 写代码写错了，可能上线炸雷，代价高且隐蔽。AI 写注释写错了，你读的时候一眼能看出来——因为它写的注释和你理解的代码对不上，这种偏差特别显眼。代码错在行为，注释错在描述，描述错了人更容易当场识别。
价值更高、风险更低，所以注释才是 AI 在代码领域的高 ROI 用法。
AI 写注释的三个甜区
用顺手后，我总结了几类最适合让 AI 写注释的场景：
- 祖传代码。没注释、没人懂、又不敢动的模块，让 AI 读一遍写注释，价值最大——它在给「死代码」续命。
- 复杂业务逻辑。那种嵌套深、规则多、改一处牵一片的逻辑，让 AI 把每段意图写出来，后来人改的时候不至于踩雷。
- 公共接口文档。对外或对跨团队的接口，让 AI 生成文档草稿，人审一遍就能用，省了手写文档的苦差。
一个反直觉的收尾
这次经历让我重新想了想「AI 在编程里该干什么」。
大家默认 AI 的主战场是「写代码」，因为那看着最酷、最有冲击力。但写代码恰恰是风险最高、收益不一定最大的部分。
反而是写注释、写文档、写测试这些「不那么酷」的活——它们是代码的「周边」，但它们的价值是累积的、风险是可控的——更适合 AI 干，也更值得让 AI 干。
AI 写代码，你还得盯着它别闯祸；AI 写注释，它顶多写得不准，你改改就行。前者是请了个会出错的程序员，后者是请了个不会闯祸的文档员。
对一个项目来说，后者可能更值。至少对我那个祖传模块，是 AI 写的注释，而不是 AI 写的代码，让它从「没人敢碰」变成了「人人能接」。