如何撰写 Code Review 评论

总结

  • 保持友善。
  • 解释你的推理。
  • 在给出明确的指示与只指出问题并让开发人员自己决定间做好平衡。
  • 鼓励开发人员简化代码或添加代码注释,而不仅仅是向你解释复杂性。

礼貌

一般而言,对于那些正在被您审查代码的人,除了保持有礼貌且尊重以外,重要的是还要确保您(的评论)是非常清楚且有帮助的。你并不总是必须遵循这种做法,但在说出可能令人不安或有争议的事情时你绝对应该使用它。 例如:

糟糕的示例:“为什么这里使用了线程,显然并发并没有带来什么好处?”

好的示例:“这里的并发模型增加了系统的复杂性,但没有任何实际的性能优势,因为没有性能优势,最好是将这些代码作为单线程处理而不是使用多线程。”

解释为什么

关于上面的“好”示例,您会注意到的一件事是,它可以帮助开发人员理解您发表评论的原因。 并不总是需要您在审查评论中包含此信息,但有时候提供更多解释,对于表明您的意图,您在遵循的最佳实践,或为您建议如何提高代码健康状况是十分恰当的。

给予指导

一般来说,修复 CL 是开发人员的责任,而不是审查者。 您无需为开发人员详细设计解决方案或编写代码。

但这并不意味着审查者应该没有帮助。一般来说,您应该在指出问题和提供直接指导之间取得适当的平衡。指出问题并让开发人员做出决定通常有助于开发人员学习,并使代码审查变得更容易。它还可能产生更好的解决方案,因为开发人员比审查者更接近代码。

但是,有时直接说明,建议甚至代码会更有帮助。代码审查的主要目标是尽可能获得最佳 CL。第二个目标是提高开发人员的技能,以便他们随着时间的推移需要的审查越来越少。

接受解释

如果您要求开发人员解释一段您不理解的代码,那通常会导致他们更清楚地重写代码。偶尔,在代码中添加注释也是一种恰当的响应,只要它不仅仅是解释过于复杂的代码。

仅在代码审查工具中编写的解释对未来的代码阅读者没有帮助。这仅在少数情况下是可接受的,例如当您查看一个您不熟悉的领域时,开发人员会用来向您解释普通读者已经知道的内容。

下一篇:处理 Code Review 中的拖延