代码审查
代码审查的总体目标是作为团队其他成员的安全网,帮助他们编写更好的代码,而不是评判他们或他们的代码。如有疑问,请假定他们有良好的意图,并且请保持友善。
目标
- 发现错误
- 发现方法中不明显的后果——此 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: 投票者都应计划在未来一两天内花一小时讨论问题,并计划如何解决它。
- 如果带有 :-1: 的 PR 在一周后没有进展,@salsakran 将介入。
如何提高代码审查的质量
有关代码审查研究的总结,请查看 实际世界中代码审查如何运作(以及不运作)。
PR 作者可以做些什么来获得更好的审查
- 通过评论代码的重要部分来指导审查员。
- 如果您需要某人的专业知识/意见,请标记该人员。
- 通过使用 注释和警告 来增强 PR 描述 - 如果您想突出某些信息,这些工具会非常有效。
PR 审查员可以做些什么来提供更好的审查
- 密切关注测试文件。请注意我们倾向于降低测试文件重要性的倾向,并有意识地努力彻底审查它们。
- 从对更改最重要的文件开始,而不是 PR 中按字母顺序排列的第一个文件。
- 如果您觉得缺少上下文,请向作者询问更多详细信息/更好的描述。
- 除非更改微不足道,否则请签出该分支并在本地运行 Metabase,包含这些更改。确保一切都按预期工作。
阅读其他版本的 Metabase 的文档。