google code review 05

原文
https://google.github.io/eng-practices/review/reviewer/comments.html
How to write code review comments (如何写审核评论)
Summary (总结)
和蔼且有礼貌的
解释你的理由
在「给出明确的方向(explicit directions) 」与「只点出问题点，让开发者做决定」之间作出权衡
鼓励开发者简化程式或增加注释，而非向你解释这问题有多复杂
Courtesy (礼貌)
一般而言，对你正在审查其程式的开发人员来说，保持礼貌与尊重的同时，确保评论是非常清楚和有帮助。

一种方法是确保

永远对程式码发表评论，而永远不要对开发人员发表评论

你可能并不总是必须遵循这种做法，但你绝对要在说出会使人不安或有争议的事情时使用这种方法。例如:

糟糕的例子:
Why did you use threads here when there’s obviously no benefit to be gained from concurrency?

为什么「你」要在使用并发没有明显益处时使用threads?

好的例子
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.

在我看来，这里使用并发模型会增加整体系统的复杂性，却没有带来任何实际性能效益。由于没有性能上的效益，我们最好在这个程式里使用single-threaded 而非multiple threads。[1]

[1] 工程师有个常犯的错误:「用极度效率的语言来解决事情，却忽略可能带来后续潜在的问题」。前面两个例子中，第一种方式虽然能用简短一句话来作结，但会让对方心生不满认为是在谴责自己。第二种方式虽然冗长，却能让对方理解到评论是针对「程式」而非「人」，避免未来团队气氛不佳或冲突。记住，有时候「慢慢来比较快」
Explain Why (说明原因)
从上面的「好」的例子中，你会注意到的一件事是「說明原因可以幫助開發者理解你為什麼發表評論」。尽管你并不总是需要在评论中包含此讯息，但有时候提供更多解释对于你的意图、正在遵循的最佳做法、提供的建议如何提高程式品质，会是十分有帮助的。

Giving Guidance (提供引导)
一般来说修缮CL 是开发者的责任，而非审核者的

你不需要为此为某个解决方案去进行详细的设计或写程式给开发者。

然而这并不意味着审核者是没有任何帮助，你應該在指出問題與提供直接指導之間取得適當的平衡。指出问题并让开发人员做出决定通常有助于他们学习，并使得未来程式审查变得更容易。同时间还有可能产生出更好的解决方案，因为开发人员可能比你更接近、了解程式的样貌。但有时直接给予明确的方向、建议甚至程式也是相当有用的。

记住程式审查的主要目的在于:

得到最佳CL
提高开发人员的技能。以便随着时间的推移，他们需要的审查会越来越少
Accepting Explanations (接受说明)
如果您要求开发人员去解释一段你无法理解的程式时，那通常會讓他們嘗試更清楚地重寫它。偶尔，在程式中添加注释也是一种恰当作法，只要它不是用来解释过于复杂的程式[1]。

仅在程式审查工具中留下的注释，对后来的读者来说没有任何帮助

这在少数情况下是可接受的。例如当你在审核某个不熟悉的领域时，开发人员会在工具中编写注释来解释的普通程式读者已经知道的内容。

[1] 此处应该是指注释虽然有用，但面对过于复杂的程式还尽量用重构来取代