ARTICLE · 1095849
第81篇:用 AI 生成注释与文档——告别＂代码一时爽＂
三个月后你打开自己写的代码，第一句话是：这谁写的？
先说一个所有人都经历过的场景。
你花了一个通宵写完功能，跑通了、提交了，长舒一口气。当时脑子里所有逻辑都清清楚楚——为什么这里要加判断、为什么那个数字是 7 天、为什么这段要单独拎出来。
三个月后。 产品说"这个地方改一下"。你打开文件，看到一堆自己写的代码，盯了十分钟，脑子里只有一个念头：
这段是干嘛的？这个 7 是什么意思？这个 if 我为什么要加？
于是你顺着代码一行行往回推，推了一小时，才想起来："哦，是因为当时那个客户投诉……"
一小时，就为了想起你自己三个月前的想法。
这就是"代码一时爽，回头火葬场"。写的时候脑子里全是上下文，写完那一刻，上下文就开始蒸发。你的代码留下了"做了什么"，却把"为什么这么做"全弄丢了。
这一篇，我们用 AI 把丢掉的东西补回来——而且不用你写一个字。
一、先搞清楚：注释和文档，到底是给谁看的
新手最大的误区，是把注释当成"给代码配翻译"，写出这种东西：
// 把 i 加 1
i = i + 1
// 循环用户列表
foruserinusers:
这类注释毫无价值。 代码本身就说了它在加 1，你再说一遍等于什么都没说；更糟的是它会过期——哪天改成加 2，注释还写着加 1，这时候注释不但在骗人，还在误导人。
所以先立一条铁律：
注释不解释"代码做了什么"，注释解释"代码为什么这么做"。
代码本身能回答 What（做了什么）和 How（怎么做的），它唯一回答不了的是 Why（为什么）。而 Why 恰恰是三个月后你最想知道、也最想不起来的东西。
// 判断是否大于 7 | // 超过 7 天的订单财务已结账，不能再退款（2024年财务流程要求） |
// 重试三次 | // 对方接口偶发抖动，实测重试 3 次成功率 99%，再多意义不大 |
// 这里排序 | // 必须先排序再去重，否则去重依赖相邻元素会漏掉 |
// 特殊处理 | // 老系统导入的数据这字段可能是空串而非 null，不判会炸 |
右边那些信息，你翻遍代码也找不到。它只存在于你当时的脑子里。
二、AI 的最大价值：看出你自己看不出的"该解释的地方"
问题来了：既然只有你知道 Why，AI 怎么帮你写？
AI 帮你的不是"编出理由"，而是"指出哪些地方需要理由"。 这一点非常关键，很多人搞反了。
你写代码时是"当局者"——所有逻辑对你都理所当然，根本意识不到哪里要解释。AI 是彻底的"外人"，它第一次看这段代码，它卡在哪，三个月后的你就会卡在哪。
正确用法分两步：
第一步：让 AI 找出"看不懂的地方"，向你提问。
第二步：你回答，AI 把你的回答写成注释。
妙处在于：你只需回答问题，不用组织语言。 回答"这个 7 是什么意思"，比"给这段代码写注释"容易一百倍——回忆比创作容易得多。
提问模板（第一步）：
你是第一次看到这段代码的人。请你只做一件事：
把你看不懂、觉得奇怪、或者猜不出原因的地方列出来，
每条写清楚：在第几行、你的疑问是什么。
特别关注这几类：
1. 写死的数字或字符串（为什么是这个值）
2. 看起来多余的判断（为什么要加这一步）
3. 顺序有讲究的地方（为什么是这个顺序）
4. 异常/特殊分支（什么情况下会走到这里）
不要给我改进建议，不要夸奖，只列疑问，最多 8 条。
代码：
【粘贴代码】
AI 会给你一张问题清单，比如：
- 第 23 行
if days > 7—— 7 是什么依据？第 41 行 先 sort 再 unique，顺序有讲究吗？ - 第 56 行 catch 里判断了
code == 'E502'，这个码代表什么？
你看着清单，脑子里立刻就有答案了。
三、第二步：口语回答，让 AI 变成注释
你不需要写规范的注释文字。用大白话回答就行，甚至可以很随意。
回答转注释模板（第二步）：
下面是我对你刚才那些疑问的回答，请把它们写成代码注释：
1. 7 天是财务定的，超过 7 天那笔账已经结了不能退
2. 必须先排序，因为去重是比相邻两个，不排会漏
3. E502 是对方接口的限流码，遇到要等一下重试
要求：
- 注释写在对应代码的上方
- 每条注释一到两句话，说清"为什么"，不要复述代码在做什么
- 用中文
- 输出完整代码文件，不要片段
注意最后那句"输出完整代码文件，不要片段"——这是本系列反复强调的铁律。AI 给你片段，你手动往里粘，十次有三次会粘错位置。
你会得到这样的结果：
# 超过 7 天的订单财务已经结账，不能再走退款流程（财务流程规定）
if days > 7:
return"订单已超过可退款期限"
# 必须先排序再去重：去重逻辑是比较相邻元素，不排序会漏掉不相邻的重复项
items.sort()
items = dedupe(items)
这就是有价值的注释。 三个月后的你打开文件，两秒钟就明白了。
四、三种文档，三种写法
注释写在代码里给自己看。文档写在代码外面给别人看（包括未来的你）。
新手最常需要的是这三种：
1. 函数说明（用途 + 参数 + 返回值）
AI 生成得最准，因为信息全在代码里。
给这个文件里的每个函数补上说明注释，包含：
- 这个函数是干什么用的（一句话）
- 每个参数是什么意思、什么类型、能不能为空
- 返回什么，特殊情况返回什么
- 什么情况下会报错
用项目里通用的文档注释格式写。输出完整文件。
2. README（项目是什么、怎么跑起来）
最值钱也最容易被跳过。 你把项目丢给别人（或半年后丢给自己），第一句问的一定是"怎么跑起来"。
根据我提供的项目信息，帮我写一份 README.md，包含：
1. 这个项目是做什么的（三句话内，讲人话）
2. 需要装什么环境、什么依赖
3. 怎么启动（一步一步的命令，能直接复制）
4. 有哪些需要自己配置的东西（比如密钥、数据库地址）
5. 常见问题（启动失败一般是什么原因）
项目信息：【描述你的项目：做什么的、用了什么技术、目录长什么样】
【可以把依赖清单文件的内容贴进来】
要求：写给一个完全没接触过这个项目的人看，别默认他知道任何背景。
"别默认他知道任何背景"这句一定要加，不然 AI 会写出"配置好环境变量后运行即可"这种废话。
3. 变更说明（这次改了什么）
每次提交都要写一句。很多人写"修改bug""更新"，等于没写。
下面是我这次改动的内容，帮我写一条提交说明：
第一行：一句话概括改了什么（不超过 30 字）
下面分条说明：改了哪些地方、为什么改、有没有影响到别的功能
改动内容：【贴上改动的代码，或者用大白话描述改了什么】
五、四个坑，别踩
坑一：让 AI 给所有代码加注释。 你说"给每一行加注释"，它就真给每一行加，满屏"// 定义变量 a"，代码密度被稀释，反而更难读。 正确做法：只让它在"看不懂的地方"加。
坑二：AI 编出来的理由，你直接信了。 跳过"提问"直接让它写，它不知道 Why 就会猜一个，比如"// 限制 7 天以内以提升性能"——听着煞有介事，实际完全不是那回事。注释写错，比没注释危害更大。 务必走两步法。
坑三：改了代码，忘了改注释。 改完代码，顺手把改动那段连同注释一起丢给 AI，问一句"这段代码和它上面的注释还对得上吗"。十秒钟的事。
坑四：把注释当烂代码的遮羞布。 一段代码要写五行注释才讲明白，多半问题不在缺注释，在于代码本身该拆了（回看第 77 篇"重构六味"）。先重构，再补注释，往往三行就自解释了。
六、随身流程（十分钟版）
功能写完、准备提交前，走三步：
- 丢给 AI，让它扮演外人提问（最多 8 条疑问）
- 用大白话回答，让它转成注释（要求输出完整文件）
- 顺手让它检查 README 要不要更新（新增依赖？新增配置项？）
这三步花的时间，通常不到你三个月后"回忆代码"所花时间的十分之一。
📦 提示词模板盒子
模板 1 · 找出"该解释的地方"（第一步，最重要）
你是第一次看到这段代码的人。只做一件事：把看不懂、奇怪、或猜不出原因的地方列出来，每条写清第几行、疑问是什么。
重点看四类：写死的数字/字符串（为何是这个值）、多余的判断（为何加）、顺序有讲究处（为何这顺序）、异常/特殊分支（何时走到）。
不要给改进建议、不要夸奖，只列疑问，最多 8 条。
代码：
【粘贴代码】
模板 2 · 把口语回答转成注释（第二步）
下面是我对你那些疑问的回答，请写成代码注释：
1.【大白话回答第一条】 2.【大白话回答第二条】 3.【大白话回答第三条】
要求：注释写在对应代码上方；每条一两句，只说"为什么"，不复述代码在做什么；用中文；输出完整文件，不要片段。
模板 3 · 批量补函数说明
给这个文件里的每个函数补说明注释，含：用途（一句话）、每个参数（含义/类型/能否为空）、返回什么（含特殊情况）、什么情况抛异常。
按项目现有文档注释格式写；不改任何业务逻辑；输出完整文件。
模板 4 · 生成 README
帮我写 README.md，含：1.项目做什么（三句话内，讲人话） 2.需要什么环境/依赖 3.怎么启动（一步步命令，可复制） 4.要自己配置什么（密钥/库地址，标在哪个文件） 5.常见问题（启动失败一般为何）。
写给完全没接触过项目的人，不要默认他知道任何背景，不要"配置好后运行即可"这类空话。
项目信息：【做什么/用了什么技术/目录结构】【依赖清单内容】
模板 5 · 注释与代码一致性检查
下面这段代码我刚改过。请检查：上面的注释和现在的代码逻辑还对得上吗？有哪条已过期或说反了？
只列"对不上"的，对得上的不用说。
【粘贴代码 + 注释】
模板 6 · 写提交说明
帮我写一条提交说明：第一行一句话概括改了什么（不超 30 字）；下面分条：改了哪些地方、为什么改、可能影响到什么。
改动内容：【贴改动代码，或大白话描述】
🔑 本篇核心口诀
注释三层：What 不写、How 少写、Why 必写。
两步法：AI 提问 → 你口语回答 → AI 转注释。
AI 不负责编理由，AI 负责找出"该写理由的地方"。跳过提问直接生成注释 = 让 AI 猜 Why = 制造错误注释。
📌 下篇预告
下一篇 《第82篇：用 AI 统一代码风格》，聊聊怎么用 AI 一次性拉齐风格，并且自动强制执行——写完自动就是规范的，不靠人盯、不靠自觉。即使你一个人写代码也有用：你和三个月前的你，其实就是两个人。