- 行为变化 → 更新 API 文档、README 或使用示例
- 注释解释为什么（意图、权衡），避免复述代码在做什么
- 过期注释是大坑：改代码时同步改注释，或直接删除
- 面向用户的破坏性变更：更新 changelog
文档改动同样走评审：跑不通的示例比没有示例更误导。
| 同步范围 | README 示例、API 文档、变更日志与行为变化对齐 |
|---|---|
| 可运行验证 | 按示例实际执行一遍并比对输出 |
评审检查项：文档与注释
文档检查：行为变化是否更新文档、注释是否解释为什么、README 与示例是否仍可直接运行、变更日志是否同步。
易错点
- 只改代码不改示例：用户照着旧文档踩坑
- 注释复述代码：代码一改注释即过期，误导后来人
数据来源与参考
- Google Engineering Practices · What to look for in a code review（Documentation）