文档与注释怎么审
文档检查的落点很具体：行为变化是否同步更新了文档或示例、注释是否在解释为什么而不是复述代码、README 里的示例是否还能直接跑通、面向用户的破坏性变更是否写进了变更日志。文档改动同样要走评审——跑不通的示例比没有示例更误导人。
基本信息
| 同步范围 | README 示例、接口文档、变更日志与行为变化对齐 |
|---|---|
| 注释标准 | 解释意图与权衡，不复述代码在做什么 |
| 可运行验证 | 按示例实际执行一遍并比对输出 |
| 过期处理 | 改动时同步更新注释，或直接删除失效注释 |
逐项看什么
- 行为变化是否更新了接口文档、README 或使用示例。
- 注释解释的是为什么（意图、约束、取舍），而不是把代码翻译成中文。
- 示例中的命令、参数、路径是否仍然存在且能执行。
- 配置项、环境变量、默认值是否与文档一致。
- 面向用户的破坏性变更是否写进变更日志并说明迁移方式。
- 文档结构是否仍然清晰：新增内容放在正确的小节，避免读者在长文档里反复找。
- 术语是否与产品及代码保持一致：同一概念用两个名字会让搜索失效。
- 文档里引用的路径、类名与函数名是否仍然存在：重构之后最容易留下失效引用。
文档问题的代价
| 问题 | 后果 |
|---|---|
| 示例过期 | 用户照着旧文档踩坑，支持成本上升 |
| 注释复述代码 | 代码一改注释即过期，误导后来人 |
| 缺少迁移说明 | 升级方不知如何改，只能读源码 |
| 配置未文档化 | 只能用默认值或靠猜，出错难排查 |
文档改动同样走评审：跑不通的示例比没有示例更误导，写错比不写代价更高。
把「为什么」写进提交信息或设计说明也可以：要点是决策依据有地方可查，而不一定非得写在代码注释里。
评审文档改动时按示例操作一遍：能跑通再批准，比只看文字描述可靠得多。