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