本文系博主译文,意译自 Google 代码评审标准

代码评审的主要目标是使基础代码随着时间推移能够保持健康强壮。一切代码评审的工具或流程都应为了保证该目标服务。

为了实现该目标,自然就会有所取舍。

首先,开发人员可以胜任改善任务。如果开发人员不去改善,那么基础代码就不会改善。话说回来,如果评审人员使得修改难以获准,那么就会挫伤开发人员改善的热情。

其次,评审人员有义务确保任一修订的质量,使得基础代码的质量不因时间的推移而每况愈下。在某种情况下,该目标显得非常棘手。因为代码的质量总会在某些时间点有所下降,尤其是时间与质量不可兼得的时候,团队为了走捷径,往往会牺牲质量以实现目标。

还有,评审人员要对所评审的代码负责。他们要确保代码始终保持一致可维护,并合乎代码评审清单中所提的要求。

因此,我们在代码评审中将以下规则作为我们期望的标准:

一般地,只要修订可以绝对改善目标代码的整体质量,无论当前是不是最佳的修改,评审人员都当予以支持。

上述准则是一切代码评审准则的中的最高准则。

当然,凡事无绝对。例如,假如某修订的目的是在目标代码中添加新的功能,但是该功能并非项目所需,此时,评审人员就有权拒绝该修订,无论代码完美与否。

相反,如果任何修订中所作的更改明确会降低系统的运行状况,一经评审人员提出,无论处理何种理由,作者必须予以整改。我们不接受任何可以明确会降低系统代码运行状况的修订

事实是,世界上并没有完美的代码,只有更好的代码。评审人员不得以要求作者去润色修订的每片代码为由,作为其获准的条件。评审人员需要客观识别基于痛点的改善,而非一味强调其认定的其它改善。评审人员所要追求的是持续的改善,而非追求完美。总而言之,某条修订若能改善目标代码的维护性和可读性,则不该拒之数天甚至数周,其原因只是因为不够”完美”。

注:本文没有任何内容可以证明修订签入的代码会明确恶化系统的运行状况。只有在紧急情况下才会如此。

1. 指导

代码评审还有一个重要功能,就是可以向开发人员传道授业解惑,譬如有些知识点,或有关语言,或有关框架,或有关通用的软件设计原则。代码评审还会沉淀有助于开发人员学习新知识的评论。随着时间的推移,那些共享的知识会成为提高系统代码运行状况的一部分。

评审人员应该对有所增益的事情畅所欲言,但是如果它并不必要,请在评论前加以前缀“NTH: ”,以让作者知晓该意见是可以忽略的锦上添花。还有,如果你的评论出于教育诉求,移除的话并不违背此标准,也请用”NTH: “作为前缀,或者表示作者不必在此修订中处理它。

2. 原则

  • 技术上的事实或数据可以否决个人的观点或偏好。

  • 有关代码风格,风格指南具有绝对权威。任何不遵守风格指南的代码风格都可认定为个人偏好。

    当前仅当:1)风格在风格指南没有约定;2)代码文本没有原有风格;此时,评审人员应优先接受作者的偏好。

  • 对于软件设计中非风格或非个人偏好的方面,当以软件设计的基本原则为基础,而不仅仅是个人意见。

    有时问题有不同的符合设计准则的解决方案。如果作者能够科学证明方案等效,则评审人员应接受作者的偏好。

  • 如果没有其它适用规则,只要不会恶化系统的整体运行状况,则评审人员可要求作者与当前基础代码保持一致。

3. 解决冲突

在代码评审的任何冲突中,开发人员和评审人员的第一反应当始终是以本文内容和修订作者指南以及评审人员指南为基础,以期达成共识。

当达成共识变得尤为困难时,请评审人员和作者召开面对面会议或视频会议,而不是仅仅试图通过代码评审中的评论解决冲突。(但是会后,请确保将讨论结果记录为修订的评论,以供未来的读者使用。)

如果上述情况依然不能解决冲突,最常见的解决方式是升级。通常,升级路径是进行更广泛的团队讨论,或让技术主管参与调解,或要求代码设计者帮助决策,或要求工程经理提供帮助。此时,别让修订的双方就此继续争论了,按第三方意见执行就好。