如何让代码审查更顺畅

投资于 沟通技巧教学

当一个开源项目刚开始时，作为维护者，您可能会很高兴看到社区对贡献的兴趣。但随着社区的壮大，通常会感到被涌入的代码审查请求淹没。即使数量可控，审查低质量的代码审查请求也会让人感到沮丧。这可能导致推迟社区代码审查（PR），而优先考虑其他事项。如果维护者无法审查所有内容，即使是有希望的工作也可能会被搁置数周未审查。

然而，有一种更好的方法。作为开源维护者，我们应该不断评估我们项目的代码贡献和审查流程，并有意识地努力改进它们。在这篇文章中，我们专注于一个特定的投资领域，根据我们的经验，这个领域可以带来巨大的回报：沟通技巧教学。

Zulip 是一款专为无缝远程工作而设计的开源团队聊天应用程序。Zulip 项目通过定期合并社区对核心产品的贡献而向前发展。

在过去的六个月里，我们已经整合了来自 125 位贡献者（其中许多是大学生）的代码，而核心团队只有 13 位工程师。我们是如何做到的？

我们将我们项目的代码贡献流程视为一个产品，它有自己的关键角色、目标和功能（更多内容将在另一篇文章中介绍）。这意味着花费时间迭代贡献流程，以便我们可以像对待任何其他要推向市场的产品一样，识别痛点和改进机会。 

教授贡献者出色的沟通技巧是我们长期投资的贡献流程的核心特征。在这篇博文中，我们将特别关注开源项目沟通的一个关键方面：提交代码审查请求以供审查。

有意识地教授贡献者这项技能，使维护者能够充分利用时间审查代码审查请求，原因有二

1. 审查清晰呈现的工作所需的时间要少得多。
2. 在深入研究代码之前，提供关于沟通的初步反馈，有助于维护者轻松识别 哪些代码审查请求值得投入时间。

我们将深入探讨我们如何教导贡献者出色地展示他们的工作。我们发现，本文描述的方法在经过最初的时间投入后，使我们项目的维护者的审查过程效率大大提高。对于贡献者来说，这也是一次很好的学习经历，他们获得了信心，并培养了继续为 Zulip 和其他开源项目做出贡献的动力。

教导贡献者如何出色地展示代码审查请求

即使是对于小的改动，来自您最强大的贡献者的代码审查请求，是什么让它们脱颖而出？根据我们的经验，最常见的是贡献者如何清晰地沟通他们的工作，这对于代码审查的难易程度有很大的影响。

清晰沟通的某些方面对于您的项目来说是特定的，而其他方面则非常通用。无论如何，清晰地解释代码审查请求中包含的工作是一项可以教导的技能。但您可能会看到问题：从头开始教导每个贡献者沟通，这种方式无法很好地扩展。我们使用以下三部分方法来解决沟通教学的规模问题

1. 编写详细、精确的文档，解释您希望在代码审查请求中看到什么。从长远来看，您需要文档能够让一位细心而彻底的新贡献者，80% 以上地达到您期望的水平。
2. 当贡献者的沟通的某些方面未达到标准时，提供清晰、可操作的反馈。
3. 迭代改进您的文档，基于您看到的贡献者遇到的痛点，以及您发现自己经常提供的反馈。

制定详细、精确的文档

记录如何在代码审查请求中进行沟通听起来可能具有挑战性，但您审查代码审查请求的经验应该让您很好地了解您期望从贡献者那里获得什么。是什么让一个出色的代码审查请求易于审查？尽可能多地写下细节，并将它们整理成一套指南或说明。

不要担心一开始就完善您的文档。正如我们在下面讨论的那样，编写出色的文档是一个迭代过程。

例如，对于 Zulip 来说，我们认为代码审查请求是对提议更改的演示。贡献者的目标应该是尽可能清晰地向审查者解释他们的更改。我们在一开始就明确表示，贡献者除了编写代码外，还需要投入大量工作来展示他们的代码审查请求。

以下是从记录我们的期望以及观察贡献者如何响应我们的代码审查请求指南的经验中，总结出的一些最佳实践

1. 您不需要完美无瑕的贡献者文档，但请努力清晰、直接地呈现信息。使用编号步骤、项目符号、标题等来组织内容。交叉链接相关文档。
2. 尽可能具体地说明什么是好的、可审查的工作。不要假设您过于挑剔或要求过多，特别是当您的要求代表快速任务时，例如拍摄需要手动测试的功能的良好屏幕截图。对于贡献者来说，遵循具体的说明比模糊的说明容易得多。链接到过去做得特别好的代码审查请求的突出示例，或说明您正在寻找的特定方面。
3. 在说明旁边分享您的要求背后的理由。这将帮助人们正确地遵循它们，并提供额外的动力。
4. 确保贡献者看到您的文档！考虑从关于您的贡献流程的总体指南和/或 GitHub 中的 代码审查请求模板 中链接到它们。

例如，我们要求贡献者在随附 Zulip 代码审查请求的描述中包含以下内容。您可能会发现类似的点对您的项目也有帮助

• 提供您的更改的概述。
• 注意与先前计划的任何差异（例如，来自您要解决的问题的描述）。
• 指出您不确定的任何未解决的问题、疑虑或决定。如果明确列出不确定点，审查过程将会顺利得多。
• 为所有视觉更改包含屏幕截图，以便可以在不运行您的代码的情况下进行审查。

提供关于沟通的清晰、可操作的反馈

无论您的文档多么清晰和详细，您项目的代码审查请求上的沟通永远不会是完美的。为了帮助贡献者改进，您不仅应该对代码更改提供直接反馈，还应该对他们展示工作的方式提供直接反馈。

这听起来可能像是更多的工作，但使用正确的方法，您可能会发现审查代码审查请求变得更少工作。想象一下，您收到一位新贡献者解释不清的代码审查请求。您会因为忽略它而感到内疚，因此您花费时间仔细研究它，并对需要改进的地方提供广泛的反馈。贡献者修复了您指出的几个错别字，然后就离开了，没有做出所需的更大的结构性更改。多么浪费时间！

您本可以通过首先关注沟通来节省时间。您不需要立即告诉贡献者他们需要做的一切才能使他们的代码审查请求准备好合并。相反，只给他们一些后续步骤，让他们更接近合并。这应该比一次性解决大量反馈对贡献者来说更容易。然后，只有当他们成功完成第一步时，您才可以提供下一组步骤。

从关于沟通的反馈开始您的审查，而不是关于代码的反馈，通常是一个更好的策略，因为

1. 通常，维护者很容易发现沟通差距，并建议解决这些差距的步骤。代码审查请求是否缺少描述、屏幕截图或指向其要解决问题的链接？提交消息中是否有错别字？如果代码审查请求没有遵循您的某些文档，那么只需留下一个指向相关文档的快速注释，作为初步审查即可。 
2. 贡献者解决您的清晰、直接的沟通反馈的意愿通常表明，其余的审查过程将更加顺利。

简而言之，审查的初始阶段应该帮助您识别可能在您的项目中取得成功的贡献者。如果一位贡献者即使在您的明确指导下，也无法或不愿意清晰地沟通以解释他们的工作，那么他们不太可能成功地做出您可以自信地整合的代码更改。

关于提供沟通反馈的一些技巧

1. 与往常一样，保持专业和尊重，同时也要直接和切中要点。使用过多的客套话可能会让贡献者不确定他们是否真的需要解决您的反馈，或者使您的反馈更难理解。
   • 良好：“请回答代码审查请求模板中的所有问题，以便为审查准备您的代码审查请求。”
   • 不太好：“如果您不介意，如果您可以回答代码审查请求模板中的所有问题，那就太好了。”
2. 提供足够的指导，以便有思想的贡献者能够解决您的反馈。当贡献者应该能够使用您的文档和其他容易获得的资源来解决问题时，不要花费大量时间逐步指导贡献者该怎么做。
   • 良好：“请将前/后屏幕截图添加到您的代码审查请求描述中；请参阅指南。”
   • 不太好：“您的代码审查请求没有屏幕截图。”— 这陈述了一个事实，但没有说明应该采取什么措施。
   • 不太好：“请将前/后屏幕截图添加到您的代码审查请求描述中。您有喜欢的屏幕截图软件吗？如果您需要帮助，请在聊天中 ping 我。以下是您应该拍摄的 5 张屏幕截图：…” 提供这种程度的支持可能不是审查员时间的良好利用，并且当您继续与这位贡献者合作时，将是不可持续的。它还会让贡献者过度依赖您，而不是靠自己弄清楚这种程度的细节。
3. 关注贡献者是否清晰地传达了他们的信息，而不是阻碍理解的细节，例如，偶尔的错别字，或对于非您的语言母语人士来说可能难以做对的细节。您的目标是教导贡献者与审查员有效地沟通，这就是您追求的目标。
   • 良好：“您需要更详细地解释这部分。”
   • 不太好：“您在第二句话中写的是 ‘posibly’ 而不是 ‘possibly’。”

迭代改进您的文档

当您提供关于代码审查请求的沟通反馈时，您会注意到您给出的反馈类型的模式。每当您一遍又一遍地给出相同的指导时，可能就该更新您的文档，以便预先向贡献者提供该指导。如果感觉像是一个次要点，请将其放入底部的“更多技巧”部分。随着时间的推移，您可以开始将主要部分拆分为您可以从其他地方链接到的专用页面。

随着您的文档变得更长更详细，您应该预料到贡献者不一定会事先阅读所有内容。没关系！您的文档对您来说仍然会增加价值：与其每次问题出现时都花时间解释，不如简单地链接到您之前编写的最佳版本解释。例如，在缺少描述的 PR 上，您可以这样写：“为了准备您的 PR 以供审核，请按照这些指南添加描述。” 通过在 GitHub 中保存此回复以及其他类似的回复，您只需几秒钟即可指导贡献者完成他们需要采取的步骤。

下一步是什么？

改进您的贡献者文档和反馈流程的工作永无止境。多年来，我们与数百名 Zulip 贡献者合作，我们仍在不断改进，包括每年左右全面修订文档的主要部分。随着我们进行这些更改，新贡献者提交的 PR 质量随着时间的推移而提高。提供反馈也变得更容易，因为有了更好的资源可以参考。

在未来的文章中，我们希望深入探讨与贡献者有效合作的其他方面，包括教授其他沟通技巧（例如，提交结构、回复审核反馈）、建立高效的多步骤审核流程等等。订阅 Zulip 博客以保持联系！

本文是我们“实用开源 (POSI)”系列文章的一部分。POSI
旨在促进关于与开源进行业务往来和为开源服务的讨论。
源。