代码审查清单可以防止愚蠢的错误

我的团队使用代码审查清单来防止愚蠢的错误给我们带来麻烦并浪费时间。在这篇文章中，我想分享我们决定实施代码审查清单的原因、清单上的内容、我们如何创建、使用和改进清单，以及它如何提高我们的效率。

为什么要创建代码审查清单？

我的团队致力于提升效率。我们遵循“约束理论”模型，识别自身存在的制约因素，并找到克服它的方法。

当我们审视冲刺板上的故事流时，我们立即将瓶颈锁定在审查流程上。故事最终往往处于“重新开启”状态（代码审查失败），而不是“完成”。当我们追踪故事代码审查失败的原因时，我们发现各种原因都与代码质量有关。但我们惊讶地发现，我们犯愚蠢错误的频率之高令人咋舌。例如，忘记运行单元测试或遗漏了某个需求。事实上，绝大多数代码审查失败都是由“愚蠢错误”造成的。

但我们偶尔也会因为漏掉某个步骤或代码审查不力，导致生产环境出现缺陷。如果告诉老板你因为搞砸了一件简单的事情就把网站关了，那可真是尴尬至极。

几年前，我读过《清单宣言：如何把事情做好》 （阿图·葛文德），并立即意识到这是一个使用清单的绝佳机会。

代码审查清单的好处

检查清单是确保涵盖复杂任务（例如代码审查）所有步骤的绝佳方法。您无需记住要查找的内容并审查代码，只需检查代码并相信清单能够确保您涵盖所有要点即可。只要您切实使用代码审查清单（并且清单结构合理），就能发现绝大多数愚蠢的错误。

我们的代码审查清单上有什么？

我们的代码审查清单一直在不断演变。以下是我个人目前的版本。

执行-确认

代码审查清单：

1. 范围- 故事优先级高，规模小，最小化蔓延，无杂散变化，将非任务变化添加到待办事项中
2. 正常工作- 规范正确且完整，实现符合规范，已创建测试计划，已创建和/或更新单元测试，主分支已合并到分支，所有更改都已测试，边缘情况已覆盖，找不到破坏代码的方法，找不到这些更改会破坏系统其他部分的任何方法，所有任务均已“完成”，零已知缺陷
3. 防御性- 验证所有公共方法的输入，如果使用不正确，则会大声失败，检查所有返回代码，安全性
4. 易于阅读和理解- 适当的抽象和问题分解、最小接口暴露、信息隐藏、命令查询原则、良好的命名、有意义的文档和注释、完全重构（使用现有代码的判断）
5. 样式和布局- 所有检查均通过，代码格式化程序运行，无异味代码样式，行长，样式与项目指南一致
6. 最后的考虑- 您完全理解代码和所做更改的影响，并且它......牢不可破，实际上已经完成，将通过代码审查，让您自豪地向其他程序员公开展示您的更改，易于审查，正确的分支，没有杂散代码，记录模式更改，主合并到分支，单元测试通过，手动测试计划完成并执行，所有更改已提交和推送，拉取请求已创建并审查，Jira 已更新

我的团队的官方清单不包括第 6 步。这是我个人提醒的，在代码审查结束时需要检查的重要事项。

有些人可能会说我们的清单太过详细。这或许是合理的抱怨。然而，这是我们团队开发的清单，而且它对我们很有效。

我们如何创建代码审查清单

我们通过分析代码审查流程中的步骤以及在拉取请求通过审查过程中遇到的问题，创建了这份清单。之后，我们将所有这些细节汇总到一份初始代码审查清单中。我们花了几周时间整理和完善这份清单。

当我们对代码审查清单感到满意后，我们将其转换为 Google 表单。我们还添加了一些额外的字段，用于记录我们想要获取的代码审查数据，例如：

• 作者和审稿人的姓名
• 代码审查花了多长时间
• 结果（通过/失败）

这些字段很重要，因为它们为我们提供了监控代码审查改进计划成功所需的反馈。

Google 表单如下所示：

我们如何使用代码审查清单

拉取请求的作者使用代码审查清单对其代码进行自我审查。他纠正了发现的任何问题，然后发布拉取请求以供审查。

审阅者使用 Google 表单版的检查清单来指导审阅过程并记录结果摘要。我们通常在两分钟内完成 Google 表单。我们会在 BitBucket 中附上针对代码本身的具体详细反馈，供作者参考。

Google 表单将代码审查结果存储在 Google 电子表格中。我们每两周都会在回顾会议中查看这些数据，评估代码审查流程的有效性，并观察其随时间的变化。

我们发现自我评审与同行评审同样重要。当你抛开细节，将代码提交到一份清单时，你会惊讶地发现很多问题。我们的清单尤其擅长发现我们忘记做的事情。例如，每个人都会偶尔忘记实现某个需求。如果没有清单提醒我们，我们很难发现拉取请求中缺少了什么。

我们如何改进代码审查清单

我们的代码审查清单是一份动态文档。我们会定期审查，并根据需要添加或删除问题。我们也鼓励程序员保留自己版本的代码审查清单。个性化清单包含仅对编写者重要的提醒（例如第 6 部分对我来说很重要 - 见上文）。

结果

我们对代码审查清单的效果非常满意。我们大幅减少了因愚蠢原因而失败的代码审查数量。每一次失败的代码审查都会浪费我们大量的时间。而由于愚蠢的原因（例如未满足需求）而失败的代码审查，是一种完全可以避免的浪费。此外，由于使用了清单，我们的代码审查速度更快，流程也更加一致。我们的效率显著提升。

我们还使用代码审查清单来识别自动化机会。刚开始进行代码审查时，我们在代码格式、样式、命名、方法复杂性等方面遇到了很多问题。我们很快意识到这些问题浪费了我们大量的时间，值得将其标准化/自动化。因此，我们配置了一个代码格式化工具和各种静态分析器。它们可以直接在我们的IDE中自动运行。这些步骤的自动化极大地提高了我们的效率——真的非常出色。

最近，我们的核对清单显示，手动测试流程的成本很高。因此，我们会在那些我们认为投资回报率高的地方加大自动化测试的投入。

进一步阅读

对于想要开始使用清单的程序员来说，有很多资源。但我在这里只提几个：

• 书籍：清单宣言：如何把事情做好（阿图·葛文德）
• Atul Gawande 的文章：清单
• 书籍：《Code Complete》（Steve McConnell 著）包含许多针对各种软件工程活动的清单
• 文章：为什么你需要一份清单：《清单宣言》中的实用要点
• 文章：更有效、更高效的同行代码审查的 11 个行之有效的实践

总结

检查表已被证明能够提高代码审查的效率。我们花了大概十几个小时才完成代码审查检查表的初始版本并开始运行。而这笔小小的投入，每天都能给我们带来回报。

你使用代码审查清单吗？请在评论区分享你的想法。