5、如何写代码审查评论
How to write code review comments
如何写代码审查评论
Summary
总结
-
Be kind.
-
Explain your reasoning.
-
Balance giving explicit directions with just pointing out problems and letting the developer decide.
-
Encourage developers to simplify code or add code comments instead of just explaining the complexity to you.
-
语气要和善；
-
解释这么评论的原因；
-
在明确指示与指出问题之间做好平衡，并让开发人员自己决定；
-
鼓励开发人员简化代码或者增加注释，而不只是让他们向你就代码的复杂性进行说明。
Courtesy
礼貌
In general, it is important to be courteous and respectful while also being very clear and helpful to the developer whose code you are reviewing. One way to do this is to be sure that you are always making comments about the code and never making comments about the developer. You don’t always have to follow this practice, but you should definitely use it when
saying something that might otherwise be upsetting or contentious. For example:
通常情况下，礼貌和尊重是很重要的，做到这两点对于其代码正在被审查的开发人员也是有帮助的。要做到这点的一个做法是，确保你只是对代码做评论，而不是开发人员本身。虽然你不用每次都这么做，但在说一些可能会令人不安或者有争议的话时，就一定要这么做。例如：
Bad: “Why did you use threads here when there’s obviously no benefit to be gained from concurrency?”
反例：“为什么这里你要使用线程？很明显这里使用并发是没有好处的。”
Good: “The concurrency model here is adding complexity to the system without any actual performance benefit that I can see. Because there’s no performance benefit, it’s best for this code to be single-threaded instead of using multiple threads.”
正例：“这里使用并发模型增加了系统复杂度，我从中看不到实际的性能优势。由于没有性能优势，这里最好使用单线程来替代多线程。”
Explain Why
解释为什么
One thing you’ll notice about the “good” example from above is that it helps the developer understand why you are making your comment. You don’t always need to include this information in your review comments, but sometimes it’s appropriate to give a bit more explanation around your intent, the best practice you’re following, or how your suggestion improves code health.
从上面的正例你会看到，那样子说明能帮助开发人员理解你的意见。虽然你不用每次都用这种形式来写评论意见，但有时应当适当地对你的意图、你所遵循的最佳实践，或者你的意见如何提高代码质量做多点解释。
Giving Guidance
给予指导
In general it is the developer’s responsibility to fix a CL, not the reviewer’s. You are not required to do detailed design of a solution or write code for the developer.
一般情况下，修复CL是开发人员的责任，而不是审核人员的。 你无需为开发人员做具体的解决方案设计或者写代码。
This doesn’t mean the reviewer should be unhelpful, though. In general you should strike an appropriate balance between pointing out problems and providing direct guidance. Pointing out problems and letting the developer make a decision often helps the developer learn, and makes it easier to do code reviews. It also
can result in a better solution, because the developer is closer to the code than the reviewer is.
但这不意味着审查人员就不用提供帮助。通常，你应该在指出问题和提供指导之间取一个平衡。指出问题并且让开发人员做出决定通常能帮助开发人员学习，并且使得代码审查变得更容易。这么做同时还能产生更好的解决方案，毕竟开发人员才是更接近代码的。
However, sometimes direct instructions, suggestions, or even code are more helpful. The primary goal of code review is to get the best CL possible. A secondary goal is improving the skills of developers so that they require less and less review over time.
然而，有时一些明确的指示，提示甚至是代码会更有用些。代码审查的主要目的是尽可能地获得最好的CL。第二个目的是为了提高开发人员的技能，以便随着时间的推移他们需要越来越少的代码审查。
Remember that people learn from reinforcement of what they are doing well and not just what they could do better. If you see things you like in the CL, comment on those too! Examples: developer cleaned up a messy algorithm, added exemplary test coverage, or you as the reviewer learned something from the CL. Just as with all comments, include why you liked something, further encouraging the developer to continue good practices.
请记住，当对人们做的好的地方（而不是能做得更好的地方）进行加强（译注：也就是鼓励）时，人们总是能从中得到学习。如果你在CL里看到了你喜欢的点，例如：开发人员清理了混乱的算法，添加了示例性的覆盖测试，或者你作为审查人员从CL里学到的东西，那么也请评注起来！同时，正如其它评注一样，这里的评注也要包含解释为什么你喜欢这个地方，以此进一步鼓励开发人员继续这些好的实践。
Accepting Explanations
接受解释
If you ask a developer to explain a piece of code that you don’t understand, that should usually result in them rewriting the code more clearly. Occasionally, adding a comment in the code is also an appropriate response, as long as it’s not just explaining overly complex code.
如果你让开发人员解释一段你不理解的代码，这通常会使得他们重新把代码写得更清晰一点。 偶尔，在代码里添加一段注释也是个恰当的回应，前提是这段注释不仅仅只是为了解释过于复杂的代码。
Explanations written only in the code review tool are not helpful to future code readers. They are acceptable only in a few circumstances, such as when you are reviewing an area you are not very familiar with and the developer explains something that normal readers of the code would have already known.
只在code review工具里做解释对于以后的代码读者是没有好处的。 只有少数情况下才会这么做，例如当你在审查一个你不熟悉的功能模块，开发人员就可以解释一下一般读者已经理解的代码。