如何写好提交注释

在《如何做到高效的Code Review》一文中提到，我们要写好提交注释，帮助评审者提高审阅质量与效率。

那么，什么样的提交注释是好的提交注释呢？本文就来讨论一下它的重要性，以及相关的规范要求。

本文概要：

正文内容如下

---

提交注释（本文指公开性提交注释，见文末说明）不应该仅仅作为代码可有可无的附代说明，而应该作为一个公开性文档，用于向未来的读者说明所做的工作以及原因。它和代码同等重要，而且也会与代码一样，存在更长时间。

1. 目的（Why）

使用标准的提交注释格式后，我们可以：

• 让评审人快速了解本次变更的意图，评判内容与意图的相符程度。
• 通过脚本自动生成变更日志（CHANGELOG）
• 识别或过滤不重要的代码变更，例如只对代码格式进行修订的那些
• 当浏览提交历史时，可以快速得到更多且更有用的信息

详述如下：

1. 让评审人快速掌握本次变更的意图

通过规范的描述，评审人可以快速掌握变更意图，并判断与实际变更内容是否相符。提升代码检视的有效性和工作效率。

1. 通过脚本自动生成变更日志（CHANGELOG）

我们在变更日志中使用以下三个部分：新功能，错误修复，重大更改。

当发布时，该变更日志列表可以由脚本生成，以及相关提交的链接。

当然，您可以在实际发布之前编辑此更改日志，但是我们仍旧可以用它来提前生成一份备选内容。

查看自上次发布以来，所有提交主题（提交消息中的第一行）的命令:

>> git log <last tag> HEAD --pretty=format:%s

当前发布中所有的新特性的 git 命令：

>> git log <last release> HEAD --grep feat

1. 识别或过滤不重要的代码变更

的确存在一些不是非常重要的代码变更，如一些代码格式的变更（添加/删除空格/空行，缩进），缺少分号，注释等。所以，在查找变更时，可以忽略这些提交——因为这些提交内容中没有代码逻辑的更改。

当使用二分法查找 （bisecting）时,你可以使用下面命令来忽略这些不重要的变更：

>> git bisect skip $(git rev-list --grep irrelevant <good place> HEAD)

1. 当浏览提交历史时，可以快速得到更多且更有用的信息

这样的格式要求，可以增加更多的 “上下文”信息。

让我们看看下面这些实际的提交注释（bad example）：

• 修复注释中的一个typo
• 修复测试。Application - 应该移除旧的iframe
• docs - 多个文档链接的修改
• docs - 删除多余的空白行
• 当从后台获取文本时，用单行空白代替双行空白。

这些信息都试图告诉我们代码变更到底发生在哪里，但它们都没有一致的共同约定，所以，它们都不是好的注释。

再看一看下面的实际提交注释（bad example）：

• 修复失败单测
• 模块信息更正
• 防止内存泄漏
• 搜索优化

你能一眼看出上面的每个提交中都改了什么吗？这些提交注释几乎没有提供有用信息，所以，也不是好的注释。我们当然可以可以查看被修改过的文件来找到具体信息，但是，这样会很慢。

以上的例子，都是因为缺少共同的约定。因此，我们订立如下格式约定。

1. 提交注释的格式说明

1. 提交注释的格式

提交注释格式 如下所示。它由三个段落组成，分别是：主题行，内容体和脚注，并由一个空行分隔。

主题行只有一行，不可多行，且行尾不需要标点符号。

内容体用于解释修改动机和修改内容。可以由多行组成。

1. 主题行

主题行占用一行，它是对本次代码变更的简洁描述，其包含类型<type>，作用域<scope>和主题内容。其中，作用域是可选项，如果产品项目组自身没有规定，也可以不写。

• <type>类型如下：

• revert（仅当revert之前的一个提交时使用）
• feat (当添加特性时使用)
• fix (当修改bug时使用)
• docs (当写文档时使用)
• refactor（当仅做代码局部重构，不增加功能时使用。）
• test (当被测试用例时使用。)
• chore (当做一些琐事时使用，比如维护一些script)
• style (在代码进行格式化，或添加必要的注释，或对文档补充标点符号等情况下使用，此时即不改变代码逻辑，也没对文档添加实质性内容）

type是必填项，且只选其一。

上面的类型列表中，权重由高到低排列。

当且仅当一次MR或PR中包含多个类型时，须选择权重高的类型使用。

• <scope>的取值

Scope 可以是指代本次代码变更的具体位置或模块。其内容可以由产品项目组指定。例如，在腾讯新闻中，可能的scope是 日历/评论/上报/视频/TAB 等。

scope是非必填项。

当包含Scope时，其应该使用半角符号 ( 和 ) 包围，并在Scope前加入半角符号 $。

• <subject> 的文本书写方式

它用于对变更的简短描述。

• 主题行应使用祈使句式和现在时。 “change” not “changed” nor “changes”
• 句首是英文单词时，首字母要大写。
• 句末不要有标点符号
• 它与行前内容之间，使用一个半角冒号和一个半角空格隔开。

1. 内容体的书写要求

内容体也应该用祈使句式和现在时。

由于主题的字数限制，可能无法完整讲清楚本次变更的动机，与之前程序逻辑的不同之处，以及一些技术细节。所以，可以在“内容体”里加入更多的说明。

内容体应该采用完整且简洁的描述来：

• 说明变更的目的
• 解释变更的机理
• 对于与性能相关的变更，要提供基准信息。

检验标准是：评审者必须能够在不熟悉上下文的情况下，通过这段描述对代码进行有效评审，否则，评审者可直接打回要求重新提交。

内容体中建议包含“TestPlan” 段落。

• TestPlan

TestPlan用于描述如何验证这次修改的代码。它有四种方式，分别是（1）自动化验证；（2）手工验证；（3）Eyes；（4）TIP。

1. 自动化验证：通常只需要写出如何运行自动化验证脚本，如Java项目可能写  mvn test  就可能运行本次变更所需要的测试用例。具体使用哪个命令，由作者根本实际情况确定。
2. 手工验证：通常不容易写自动化测试用例，或还没有写。此时应该列举本次修改所需要的手工验证场景，如前图例。
3. eyes：有一些变更比较简单（如配置项），或者无法或很难构造用于验证的运行场景，可以写 'eyes'。此时，评审者须格外给予关注。
4. TIP：是指 Test in Production，表示只能在生产环境上验证。在这种情况下，需要工程团队格外给予关注。

5. 脚注

脚注与内容体之间以空行分隔。

脚注内容包括两部分，一是Relnote，二是关联单号，二者之间以一行空白分隔。且两项均为可选项，应根据实际情况填写。

• Relnote

Relnote的内容将由工具自动生成ChangeLog。通常是该未来版本发布中比较重要的变更，既可能是重要的新特性，也可能是重大缺陷的修复。

若本变更需要写入ChangeLog，格式如下：

Relnote: 作为关键字，独占一行。并另起一行，填写具体ChangeLog内容。且二者之间不留空行。

否则，可以不写 Relnote 段落。

• 关联单号

关联单号是指：本次提交变更与哪些工单关联。

根据原子性提交原则，一般只与一个单号相关联。

只有类似“当本次只修改一处，同时修复多个Bug”的情况下，才能够关联多个单号。
（关于“提交原子性原则”，请参见《每次提交代码为什么要具有原子性？》）

feat、fix类型，必须与单号关联。

refector类型，如果重构内容较大，建议先建立任务单，然后与重构任务单关联。如果是在当前开发某个特性或修复某个bug的工作，与该需求单或bug单相关联。

关联单号的格式必须使用以下几种：

story：#12345

Bug：#56789

issue：#23456

1. 代码回滚（Revert）时的注释写法

    如果某次提交是回滚（Revert）之前某一次提交的内容，主题行应该以`revert: `开头，然后写这次Revert提交的主题内容。

    在内容部分，应该写: `本次Revert的提交是<hash>。”其中，hash部分应该填写被回滚的那一次提交的SHA值。

    这种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”，因此以相同的时态进行书写可以使事情保持一致。