Google Testing Blog の Code Health: Respectful Reviews == Useful Reviews のざっくり和訳です。
コードレビューのコメントを丁寧に解決していくため、これらの tips を活用しましょう。
レビュワーやオーサー(コードを書いた人)として
DO: 相手に能力があると想定しよう。オーサーの実装や、レビュワーのコメントは、あなたの知らない事情を考慮したものかもしれません。まずは経緯を理解するために質問しましょう。
DO: 根拠や文脈を示そう。ベストプラクティスのドキュメントや、スタイルガイド、設計資料などのことです。これらは理解の助けになったり、学びもあります。
DO: コメントがどう受け取られるかを考えよう。誇張、ジョーク、絵文字の受け取り方は人によって違うことを意識しましょう。
Author Don't | Author Do |
---|---|
短い名前がいいと思うので、やれと言われない限りは変えたくありません :) | 自明、総称的な言葉は省くことが、ベストプラクティスで提案されています。この提案と、もらったコメントとの落とし所がちょっと思いつきません。 |
DON'T: 人を批判しないようにしよう。代わりに、コードについて議論しましょう。意味的に人を対象にしたコメントであっても、コードの質を上げるという本来のゴールから、"あなた" や "あなたの" といった言葉遣いによって話題がそれないようにしましょう。(訳注:日本語ではあなたといった言葉をあまり使わないので起こりにくい話です)
Author Don't | Author Do |
---|---|
あなたはなぜこの方法を使っているのですか?あなたは必要以上に複雑にしています。 | この並行モデルによって、目に見えたパフォーマンス改善がない割にシステムが複雑になっています。 |
DON'T: 厳しい言葉を避けよう。ネガティブなトーンのレビューコメントは、有益ではない傾向があります。例えば、ある研究ではとてもネガティブなコメントがを有益だと受け取ったオーサーは 57% だったのに対し、より中立的なコメントだと 79% でした。
レビュアーとして
DO: 具体的で、アクション可能なフィードバックをしよう。具体的なアドバイスがない場合、どうしてオーサーがそのような書き方をしたのか尋ねるといいかもしれません。
Reviewer Don't | Reviewer Do |
---|---|
これは分かりません。 | これが最適化だとしたら、コメントを足してくれませんか? |
DO: 些細な指摘や、オプショナルなコメントは、そうだと分かるように書こう。'Nit' や 'Optional' といった言葉をつけたりすることで、レビュアーの感覚がオーサーに伝わりやすくなります。(訳注:Nit (nits) についてはプルリク時のコメント略語が参考になります)
オーサーとして
DO: コードについてはっきり説明したり、レビュアーのコメントに答えよう。レビュワーからのフィードバックに答えるときのコツです。これができないと、コードの改善に対する受容性の欠如を引き起こすかもしれません。
Author Don't | Author Do |
---|---|
それがいい場合もありますが、ここでは違いますね。 | このように実装した理由をコメントに書きました。 |
DO: フィードバックに反対するときは、あなたのアプローチの長所を説明しましょう。合意に至れないときは、Google が出しているコードレビューにおける衝突を解決する方法を参考にしましょう。