谷歌最佳实践 - 如何写代码审核评论

来源

如何写代码审核评论

概述

• 友善一些
• 清楚的阐述你的理由
• 要在清楚地给出方向和指出问题后让开发者自己决定之间做好平衡
• 鼓励开发者简化代码或者添加说明，而不是解释代码为什么这么复杂

礼貌

通常当你在审核别人的代码时，友善、尊重、提供清晰、有效的意见对于开发者是非常重要的。做到这个的方法是在评论中只针对代码，而不是开发者。你不一定需要一直按照推荐实践来操作，但是当你说一些负面的或者有争议的意见时一定要按照规范来。例如：
错误：“为什么你在这种明显不需要并发的场景使用多线程呢？”
正确：“在这里使用并发只是增加了系统的复杂度我却没有发现任何实际的性能提升。因为没有性能提升，在这里最好使用单线程而不是多线程。”

解释原因

你发现刚才“正确”的例子中，能够帮助开发者理解为什么你要写下那些评论，有时候你要对你的目的做多一些解释，比如你遵循的最佳实践，或者你对于提升代码质量的一些建议

提供指导

通常修复变更提交是开发者的责任而不是审核者。作为审核者你不应该进行解决方案的详细设计或者帮助开发者编码。
但这并不意味着审核者不应提供任何帮助，尽管你要合理的掌握指出问题和直接提供解决方案之间的平衡。单单指出问题并且让开发者自己做出决定一般能够帮助其成长，审核行为也会更加简单。通常也会产生好的结果，因为开发者比审核者更理解代码和需求。
然而有时候直接的说明、建议、甚至代码会更有帮助。毕竟代码审核的目的就是使得提交的内容是最优的。第二目标才是提高开发者的技能，今后的审核能够更加快捷。

接受解释说明

当你要求开发者说明一块你无法理解的代码时，通常最终会要求开发者将代码重写得更加清晰。偶尔情况下，在代码中添加注释也是一个很好的回复，只要不是解释一块过于复杂的代码。
说明只写在代码审核工具中对于今后阅读代码的人并不是很有帮助。这在某些情况下才可以接受，例如你正在审核一个比较不熟悉的功能，开发者尝试给你解释一些其他大部分审核者都已经了解的内容。

下一篇：如何处理代码审核中的负面反馈