代码审查
代码审查的总体目标是作为我们团队其他人的安全网,帮助他们编写更好的代码,而不是评判他们或他们的代码。如有疑问,请假设他们是出于好意,并且保持友好。
目标
- 捕获 bug
- 捕获某个方法不明显的后果——这个 PR 会让未来的代码更难保证安全或更容易出错吗?
- 对于在没有讨论的情况下编写的代码,代码审查可以作为一个合理的检查,以确保正在采取正确的方法。
- 指出 PR 对 Metabase 的未触及部分的影响。
- 指出使用了良好方法或风格的地方。代码审查不是一场仇恨盛宴。除非一个 PR 完全糟糕,否则应该提出等量的优点和缺点。
进行代码审查的心态
作为审查员,你的首要目标是充当安全网,防止坏代码被合并。 “坏”的定义是高度主观的、依赖于上下文的,并且会随着产品时间和成熟度而变化。
当你发现明显的错误时,花时间说明为什么你认为它们是错误。
如果你看到不同意某种方法的地方,请说出来。但是,也要花时间去理解作者为什么做出了某个选择。你应该假设作者根据当时所知做出了一个好的决定。你可能拥有不同的知识集合,并且看到不同的结果。深入研究这些。他们可能会看到你没看到的东西,反之亦然。
寻找可以借鉴的技巧、技术或惯用法。你的同事都是聪明人。很有可能他们有一些你可以学习的技巧。一定要让他们知道。
接受代码审查的心态
审查员是在帮你。他们是为了帮助你做到最好。最优秀的人都有教练、编辑和导师。你的代码审查员也应该以同样的方式帮助你。在他们更有经验的情况下,这可以是直接的指导。在他们更初级的情况下,他们拥有一双新鲜的眼睛,可能会让你质疑根深蒂固的假设。
当审查员不同意你采取的方法时,请努力理解原因。他们可能知道你不知道的事情或看到你没看到的结果。虽然他们可能没有像你一样深入地思考 PR 的具体主题,但他们同样可能正在考虑 PR 对你可能不关注的领域的影响。
如果有人对你的 PR 强行给出 :-1:,请格外耐心。深入了解他们为什么认为 PR 有缺陷。以改进 PR 为目标来开始对话,而不是为你的方法辩护。在辩论中做得更好不会给你加分,但在交付更好的代码和更好的产品方面你会获得加分,无论灵感或想法来自哪里。
流程
- 每个复杂度显著的 PR 都需要由团队中至少一名其他工程师(或 @salsakran):+1: 才能合并。
- 将你认为应该审查你 PR 的人添加到 PR 的分配者中。审查员可以在审查后将其删除,或决定他们不是合适的审查员。
- 影响其他工程师工作的代码应由那些工程师审查。
- :+1: 是“我没问题”的默认表示。
- :+0: (我编的) 表示“我不太满意,但其他人表示‘+1’意味着可以合并”。
- :-1: 是硬性否决。这应该在普通的 PR 中谨慎使用,并且只用于缺少测试、公然违反风格指南或破坏代码库其他部分所依赖的假设的情况。
- 如果你在没有讨论设计或与可能受影响的其他工程师讨论影响的情况下进行了重大分支,你应该会收到一个 :-1:,并且不要纠结于重构有争议的部分。
- 任何带有 :-1: 的 PR 都不能合并,直到问题得到解决。
- PR 的所有者和投 :-1: 的人应解决方法上的分歧。
- 如果出现僵局,@salsakran 将投出决定性的一票。僵局应是罕见的。
请注意,这些 :+1:、:+0: 和 :-1: 应该明确地在评论中说明,而不是作为 GitHub 上 PR 主要描述的反应。从 :-1: 变为 :+1: 也应在评论中明确说明。
时间安排
- 高优先级问题的 PR 应尽快进行代码审查。
- 里程碑问题的 PR 可以等待几天。
- 如果 PR 上没有 :+1:,则 PR 创建者有责任跟进其他人并获得代码审查。重申一下,PR 需要 :+1: 才能合并,如果尚未审查,则由 PR 的发起者负责寻找审查者。
- 如果存在 :-1: 且没有明确的解决方案,PR 创建者和投 :-1: 的人应计划在接下来的几天里花一个小时来讨论问题,并计划如何解决它。
- 如果 PR 在一周后仍未有任何进展且有 :-1:,@salsakran 将介入。
如何提高代码审查质量
有关代码审查研究的摘要,请查看 现实世界中代码审查的运作(及不运作)。
PR 作者可以做些什么来获得更好的审查
- 通过在代码的重要部分添加注释来指导审查者。
- 如果您需要某人的专业知识/意见,请标记那个人。
- 通过使用 注意和警告 来增强 PR 描述——如果您希望某些信息突出显示,这些工具会很有用。
PR 审查员可以做些什么来给出更好的审查
- 密切关注测试文件。注意我们倾向于给予测试文件较低的重视程度,并有意识地努力彻底审查它们。
- 从对更改最重要的文件开始,而不是 PR 中按字母顺序排列的第一个文件。
- 如果您觉得缺乏上下文,请向作者询问更多详细信息/更好的描述。
- 除非更改是微不足道的,否则请签出该分支并在本地运行 Metabase 以包含更改。确保一切正常。
阅读其他版本的 Metabase 的文档。