用 Codex 写文档和注释:让代码自己说清楚(建议收藏)

文档和注释不是写给现在看懂的人，是写给半年后忘了的你和接手的同事。Codex 最适合干这种「明明该做、就是懒得做」的苦活。

人写文档的痛是：写的时候觉得多余，三个月后自己看不懂；不写，别人看代码像考古。

这篇要让文档变成写完代码顺手产出的东西，而不是独立的大工程。

OpenAI Codex 官方界面 · 截自 openai/codex 官方仓库

先记三个数字，文档这件事就轻了。

让 Codex 生成注释时，强调只写『为什么』：『为什么这里要加锁』『为什么用这个魔法数字』。代码本身已经说了 what。

烂注释是『把代码翻译成人话』——纯属废话。好注释解释意图、边界、坑。

给它指令：『给这个函数补注释，重点解释设计意图和容易踩的边界，不要重复代码在说什么。』

让 Codex 读整个模块，生成 README：它干嘛的、怎么用、有哪些坑、依赖什么。

给模板更稳：『按「功能 / 快速开始 / API 示例 / 注意事项」四段写，控制在半页内。』

新人入职第一件事就是看 README——这页值钱，值得让它写好。

提 PR / 发版前，让 Codex 对比改动生成 changelog：新增、修复、破坏性变更分别列。

指令给受众：『写给用户看，说清『升级后要注意什么』，别说技术细节。』

好的变更说明让使用者零成本升级，少一堆『怎么报错了』的工单。

本地渲染 · 对应本文任务示例

Codex 写的注释可能和代码实际行为对不上——尤其代码改过、它按旧逻辑写。生成后扫一眼关键处。

它容易写正确的废话（『这个函数计算总额』），这种要打回去重写，逼它写 why。

把文档当代码的一部分：改了逻辑，就让它同步更新对应注释，别让文档撒谎。

把『写注释 / 生成 README』做成提交前的固定一步，和测试、评审并列。

在 PR 模板里加一句『文档是否更新』的勾选，让它成为默认动作。

对外发布的库，文档质量就是产品力，值得单独让 Codex 过一遍。

文档的价值在复利：今天花十分钟写，未来省十次抓瞎。Codex 把这笔钱的成本降到近乎为零。

记住原则：写 why 不写 what、顺手不攒、改代码必改文档。代码就真的会说话了。

读懂旧代码，下一步是换骨架。下一篇写《用 Codex 做老框架迁移：在不停工的前提下换血》——对照旧实现、逐模块搬、保测试。关注「AI云前哨」。