如何做到高效的Code Review

乔梁 | 2021-03-04

Code Review 一直是软件工程中的一个好实践。本文仅简单阐述 Code Review 对工程团队的重大意义,以及高效 Code Review 的必要实践。

主要内容包括:

  • Code Review 对工程组织的意义
  • 提交者应该做的事
  • 审阅者应该做的事

一、Code Review对工程组织的意义

高质量的 Code Review ,可以:

  • 提高工程组织开发流程的标准化程度。
  • 在质量一致性的前提下,让工程团队可快速扩展。
  • 有意义且有用的注释帮助提升整个工程组织的水平。
  • 成为质量保证和知识共享的重要组成部分,如高质量的评论。
  • 帮助工程组织建立健康的反馈文化:工程师乐于接收和接受所有工作领域的反馈,而不仅仅是在编码方面,因为它已成为工作的日常工作。
  • 提供客观的工程技能证据。

二、提交者三问:

在提交 Code Review 时,需要对变更做出适当解释么?

是的,你需要做出适当解释。不要理所当然地认为,你的代码是自解释的。

为了得到最佳的 Review 效果,并帮助您的团队规模扩展( Scale ),每次提交的代码变更 Message 都应包括:设计概要,以简要说明该变更背后的动机。

如果评审者需要通过阅读代码变更,并从中推断出其基本设计原理时,则 他/她 真的很难提供高质量的代码审阅。

所以,要求提交者在提交代码审查时,必须要解释其修改代码的动机,是非常公平合理的。所以,我们应鼓励提交者在其提交注释( Commit Message )中对变更做出一定的解释,从而提高代码文档的质量。

关于 Commit Message相关内容,参见《如何写出好的Commit Message》一文。

Test Plan是否充分?

每个提交的代码变更注释都必须包含“ Test Plan ”这部分,即如何验证提交者所做出的修改。这相当于一份自测计划。

“ TestPlan ”中写什么取决于变更的严重性和当前测试范围。

如果更改包含新的或变更条件复杂,则变更应该包含对其进行单元测试的代码是合理预期。

如果自动化集成测试的覆盖范围不足,则可能需要进行一些手工测试的步骤。在这种情况下,“TestPlan”还应包括有关测试方案和输出的信息。当本次代码的修订已经改变了程序的输出时,将新的输出包括在“TestPlan”部分中非常有用。

关于 Test Plan 的实践,参见《如何写出好的Commit Message 》一文。

这个代码审查反馈评论对我有用吗?

这个问题是验证代码审查反馈是否必要的一种简单而有效的方法。

归根结底,工程师应该将代码审查视为有用的开发工具,而不是无关紧要的工作来源。如果您认为特定的评论对您没有帮助,请删除它。

不利于代码审查的经典示例是与代码格式相关的注释。代码样式和格式应由自动化工具而非工程师验证。

三、评论者四问:

如果代码写的不错,我是否要给予正向反馈?

是的,我们鼓励给予正向反馈。

在一个全是聪明人的组织中,我们认为干净的代码和整齐利落的测试覆盖是理所当然的。所以,在代码审查的反馈中,常常只包含代码中所发现的一些问题。这是非常不幸的,因为大多数人需要积极的反馈才能感到投入和动力——工程师也不例外。

当审阅者看到代码中的好东西时,他们应该喊出来,并给出积极的反馈。这有助于改善团队动力,这种积极的反馈通常具有感染力。与所有代码反馈注释一样,任何正向反馈都应是比较具体的,它可以解释为什么某段特定代码写的好。

我的 Code Review 评论写的够好么?

不管评论是正向的,还是负向的,任何代码审查的评论都应该做到“不言自明”。

那些对于审查者而言似乎显而易见的东西,很可能对于接收审查反馈的工程师来说,其审查反馈可能还不是很清楚明白。如有疑问,最好能进行过度解释,而不是提供简短的反馈。因为简短的反馈可能引发更多的疑问,并需要更多的反复沟通。

当然,这些解释也可以很简单,例如“减少重复”,“提高覆盖率”或“使代码更易于测试”。除了让评论者的评论更清晰外,这些类型的解释还有助于加强团队渴望达到的设计原则。

另外,当指出设计原则、代码规范等反馈点时,若该反馈点内容比较生僻,建议附上一个外链接,以指向其内容解释,供被评者参考学习。

我是否要对提交者的付出表示赞赏?

是的。无论提交代码的结果如何,总要赞赏他们的辛苦工作——它能培养出强大而积极进取的团队。

某些代码变更的质量不是最高的,因此需要进行重新处理。在这种情况下,即使他们的代码需要重新编写,仍然必须承认作者所做的变更非常重要。表示赞赏的最好方法是在代码审查中努力做到:通过提供高质量的反馈并提供体面的解释,对其中的好主意(每次提交的代码中总有好东西吧!)给予肯定,并使用“谢谢”。

我写的评论是否太学究了?

对代码变更的评审注释太多,以至于将重要的问题(实际上是需要解决的问题)淹没在大量次要的建议中。这是应该避免的。假如是由于提交者不了解团队编写代码的要求或缺少必要的指导,则应该进行线下面对面的辅导。

对于某个特定的团队来说,过于详细的评论可能会减慢审阅周期,并且会给审阅者和受审者造成摩擦。拥有清晰的评审期望,评审示例,以及积极的评审文化是避免冗长而繁琐的评审周期的好方法。

四、小结

总之,进行正式的代码评审过程有助于提高代码质量,团队学习和知识共享。当团队中的每个工程师都意识到以下两件重要的事情时,工作质量就会提高:

别人将阅读我的代码,所以最好代码变得更好,而且,我要解决收到的所有评论,因此我应该尝试第一次就编写好我的代码,就可以节省以后的精力。

当代码审查成为日常习惯时,团队将练习每天提供和接收反馈。这是成长与改善的关键。