在《
如何做到高效的Code Review
》一文中提到,我们要写好提交注释,帮助评审者提高审阅质量与效率。
那么,什么样的提交注释是好的提交注释呢?本文就来讨论一下它的重要性,以及相关的规范要求。
本文概要:
正文内容如下
提交注释(本文指公开性提交注释,见文末说明)不应该仅仅作为代码可有可无的附代说明,而应该作为一个公开性文档,用于向未来的读者说明 所做的工作以及原因。它和代码同等重要,而且也会与代码一样,存在更长时间。
提交注释(本文指公开性提交注释,见文末说明)不应该仅仅作为代码可有可无的附代说明,而应该作为一个公开性文档,用于向未来的读者说明 所做的工作以及原因。它和代码同等重要,而且也会与代码一样,存在更长时间。
目的(Why)
- 让评审人快速了解本次变更的意图,评判内容与意图的相符程度。
- 通过脚本自动生成变更日志(CHANGELOG)
- 识别或过滤不重要的代码变更,例如只对代码格式进行修订的那些
- 当浏览提交历史时,可以快速得到更多且更有用的信息
让评审人快速掌握本次变更的意图
通过脚本自动生成变更日志(CHANGELOG)
识别或过滤不重要的代码变更
当浏览提交历史时,可以快速得到更多且更有用的信息
- 修复注释中的一个typo
- 修复测试。Application - 应该移除旧的iframe
- docs - 多个文档链接的修改
- docs - 删除多余的空白行
- 当从后台获取文本时,用单行空白代替双行空白。
- 修复失败单测
- 模块信息更正
- 防止内存泄漏
- 搜索优化
提交注释的格式说明
提交注释的格式
主题行
类型如下:
- revert(仅当revert之前的一个提交时使用)
- feat (当添加特性时使用)
- fix (当修改bug时使用)
- docs (当写文档时使用)
- refactor(当仅做代码局部重构,不增加功能时使用。)
- test (当被测试用例时使用。)
- chore (当做一些琐事时使用,比如维护一些script)
- style (在代码进行格式化,或添加必要的注释,或对文档补充标点符号等情况下使用,此时即不改变代码逻辑,也没对文档添加实质性内容)
的取值
的文本书写方式
- 主题行应使用祈使句式和现在时。 “change” not “changed” nor “changes”
- 句首是英文单词时,首字母要大写。
- 句末不要有标点符号
- 它与行前内容之间,使用一个半角冒号和一个半角空格隔开。
内容体的书写要求
- 说明变更的目的
- 解释变更的机理
- 对于与性能相关的变更,要提供基准信息。
TestPlan
- 自动化验证:通常只需要写出如何运行自动化验证脚本,如Java项目可能写 mvn test 就可能运行本次变更所需要的测试用例。具体使用哪个命令,由作者根本实际情况确定。
- 手工验证:通常不容易写自动化测试用例,或还没有写。此时应该列举本次修改所需要的手工验证场景,如前图例。
- eyes:有一些变更比较简单(如配置项),或者无法或很难构造用于验证的运行场景,可以写 'eyes'。此时,评审者须格外给予关注。
- TIP:是指 Test in Production,表示只能在生产环境上验证。在这种情况下,需要工程团队格外给予关注。
脚注
Relnote
关联单号
只有类似“当本次只修改一处,同时修复多个Bug”的情况下,才能够关联多个单号。(关于“提交原子性原则”,请参见《每次提交代码为什么要具有原子性?》)
feat、fix类型,必须与单号关联。
refector类型,如果重构内容较大,建议先建立任务单,然后与重构任务单关联。如果是在当前开发某个特性或修复某个bug的工作,与该需求单或bug单相关联。
关联单号的格式必须使用以下几种:
story:#12345
Bug:#56789
issue:#23456
代码回滚(Revert)时的注释写法
三、其它说明
什么是公开性提交注释?
“公开性”是与“本地(Local)"相对应。
在使用 Git 等分布式版本控制工具时,开发者可以将其变更临时提交到Local的代码仓库进行保存,并写下提交注释(Commit Message),但此时的提交注释仅作者本人可见(除非其他人克隆作者的这个本地仓库),因此并非是公开的。
另外,作者本人为了完成一个开发任务,可以在本地做多次提交操作,每次提交都可以编写提交注释,用于记录自己的工作进度。
当作者完成一个开发任务,希望与团队其他人的代码合并时,应使用 squash merge的方式,并谨慎编写恰当的合入注释。此时的注释即为“公开性提交注释”,其旨在帮助评审者理解作者的意图,并作为文档留存。
主题为什么要用祈使句和现在时?
现在,大家都习惯于用“我已经完成了哪些变更”的思路来编写提交注释,而使用祈使句,可以帮助评审者更容易识别出作者的意图。
例如下面这个提交注释的主题:
Renamed the iVars and removed the common prefix.
与下面这个主题内容进行对比
Rename the iVars to remove the common prefix
下面这个主题内容告诉某人这次变更的意图是什么(即:将要做什么),而不是你做过了什么。另外,如果你现在去查看 Git 代码仓库的历史记录,你会看到,Git所生成的注释也是以这种方式和时态编写的——例如“Merge”而不是“Merged”,“rebase”不是“rebased”,因此以相同的时态进行书写可以使事情保持一致。