如何编写代码评论

概要

• 要和善和蔼
• 说明解释你的理由
• 给出明确的方向，指出问题，让开发人员来决定。
• 鼓励开发人员简化代码或添加代码注释，而不是仅仅向您解释代码的复杂性。

礼貌

一般来说，礼貌和尊重是很重要的，同时评论也要对你正在审查代码的开发人员非常清晰和有帮助。确保你总是对代码进行评论，而绝不是对开发人员进行评论。你不必总是遵循这个惯例，但是当你说一些可能会令人心烦或有争议的话时，你绝对应该使用它。

反例:“为什么你在这里使用线程，而且显然没有从并发中获得任何好处?”

正例:“这里的并发模型增加了系统的复杂性，但我看不到任何实际的性能优势。因为没有性能上的好处，所以这段代码最好是单线程的，而不是使用多个线程。

解释为什么

关于上面的“好”示例，你会注意到一件事:它帮助开发人员理解你为什么要进行评论。你并不总是需要在评论中包含这些信息，但是有时候，对于你的意图、你所遵循的最佳实践，或者你的建议如何改进代码健康状况，给出更多的解释是合适的。

给予指导

一般来说，修复CL是开发人员的责任，而不是评审员的责任。你不需要为开发人员进行详细的解决方案设计或编写代码。

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

然而，有时直接的指示、建议甚至编码更有帮助。代码评审的主要目标是获得尽可能好的CL。第二个目标是提高开发人员的技能，使他们需要的审查时间越来越少。

接受解释

如果你让开发人员解释一段你不理解的代码，通常会导致他们重写代码时更清晰。偶尔，在代码中添加注释也是一种适当的响应，只要它不仅仅是解释过于复杂的代码。

仅在代码评审工具中编写的解释对将来的代码读者没有帮助。它们只在少数情况下是可接受的，例如当你正在评审一个你不太熟悉的区域，并且开发人员解释一些代码的普通读者已经知道的内容时。

下一章：如何处理代码推回