文档与代码同步
改动后必查清单
- README 的安装/用法示例是否还能跑通(示例代码必须实际执行验证)
- 配置项、命令参数、字段名是否与实现一致
- 版本号:package.json 与文档里引用的版本是否一致
- CHANGELOG 是否记录了本次变化(遵循 Keep a Changelog)
- 注释:行为变了,旧注释是否变成误导
原则
- 过期文档比没有文档更糟:宁可直接删除过时段落,也不要留着错误示例
- 文档里出现命令时,用代码块并标注运行环境(版本、平台)
- 无法验证的行为不要写进文档;写"未验证"而不是"应该可以"
- 文档改动与代码改动放在同一个提交里,保证可追溯