最新

AI 怎么给代码加注释

老代码没人写注释,接手全靠猜。这篇讲怎么把要求说清、粘多少代码合适、怎么核对它没顺手改逻辑。

接手一份没有注释的老代码,函数名还看得懂,里面的判断和取反就得一行行推。把文件丢给 AI 让它补注释,比逐行手写快得多,代价是它会顺手改点别的东西,回来的注释也常常只是把代码翻译成中文。

入口在哪

三个入口,按你手里有多少代码选:

  • 对话网页,比如 ChatGPT、Claude、Kimi、通义千问这一类:适合单个函数、单个文件,粘上去就能问。
  • 编辑器里的 AI 插件:适合已经在改的项目,能直接读到当前文件和上下文。
  • 命令行里的编程助手:适合一次处理多个文件,但要先确认它只读不写。

不管走哪条路,关键都不在入口,而在提示里有没有把范围限定死。

具体步骤

  1. 先定规范:哪种语言的标准注释格式、写文档注释还是行内注释、用中文还是英文。团队有规范就把条文一起贴进去。
  2. 粘代码时带上上下文:这个文件干什么用的、被谁调用、有没有特殊约定,比如不允许往外抛异常。只贴孤零零一个函数,它只能靠猜。
  3. 把要求写成三条:只新增注释不改动任何一行代码;注释解释为什么要这么写,不要复述代码;拿不准的地方用提问的方式标出来,不要编。
  4. 长文件分批处理,一次一个函数或者一个类。整包粘进去多半会被截断,后半段的注释就开始糊弄。
  5. 拿回来的结果不要整体覆盖,先看差异:哪几行变了、变的是注释还是代码。
  6. 确认只动了注释再提交,提交信息里写清楚这一步只加注释,以后回溯时省事。

几个坑

  • 它顺手收拾代码。重命名变量、删掉它认为多余的判断、调整缩进,这些都遇到过。所以一定要看差异,别听它嘴上说没改。
  • 注释复述代码。类似「如果 i 大于零则自增」的写法对读的人没有帮助,要的是它为什么在这里判断、这个边界值怎么来的。
  • 参数注释和签名对不上。函数签名改过、注释没跟着改,比没有注释更容易误导人。
  • 一次贴太长被截断。前面注释写得很细,后面明显敷衍,多半是长度到顶了。
  • 把密钥、内网地址、真实客户数据一起贴进去。贴之前先替换成占位符,这一步没有补救办法。
  • 项目规范要求英文注释,它却回了一堆中文,或者反过来。这条要在第一步就说清。

怎么验证

  1. 看差异统计:应该只有新增行,且新增的都是注释行。一旦出现删除行就逐条看。
  2. 跑一次构建或编译,再跑一遍测试,确认行为没有变化。
  3. 随便抽三个函数,遮住代码只看注释,看能不能说清这段在干什么、为什么这么干。说不清就是废话注释。
  4. 把鼠标悬停在函数名上,看编辑器有没有把文档注释显示出来,格式不对这里就是空的。
  5. 用项目的 lint 规则过一遍,注释格式不合规会被报出来。

常见问题

让它加注释会把代码改坏吗

会。最常见的是重命名和删掉它判断为多余的逻辑,而且它不会主动提醒你。所以永远不要整体覆盖,逐块对照差异再决定是否接受。

写中文注释还是英文注释

跟项目现有代码保持一致,别一半中文一半英文。团队没规定就按项目里注释最多的那种语言来,风格不统一的问题先统一再补。

整个项目能一次处理完吗

不建议。一次一个文件更容易核对,出问题也好回退。真要批量做,先在分支上跑,跑完用差异统计筛出动了代码的文件单独复查。

一句话总结:让它只加注释、你只看差异,这两条守住了,AI 补注释才真的省时间。