View on GitHub

google-engineering-practices

Google's Engineering Practices Documentation Japanese Translation

コードレビューのコメントの書き方

まとめ

礼儀

一般に、コードをレビューしている開発者に対しては、非常に明快な態度を取り、助けに満ちた気持ちを示すとともに、丁寧に、尊敬の気持ちを持って接することが大切です。このことを実践する方法の1つは、決して開発者についてコメントをしないで、必ずコードについてコメントをすることを忘れないことです。このプラクティスには必ず従わなければならないというわけではありませんが、このように話さなければ相手を怒らせてしまったり、争いのもとになってしまう可能性のあることを言う場合には、このプラクティスを絶対に使わなければなりません。以下に例を示します。

悪い例: “どうしてあなたはここでスレッドを使用したのですか? この場所で並列性から得られる恩恵がないのは明らかですよね?”

よい例: “この場所の並列性モデルはシステムに複雑さを加えていますが、私には具体的な性能の恩恵は得られていないように見えます。性能向上が得られない場合には、このコードはマルチスレッドにする代わりにシングルスレッドにするのが最適です。”

なぜかという理由を説明する

上の「よい」例で気がつくことの1つは、開発者が「なぜか」という理由 (why) を理解することをコメントが助けているという点です。あなたのレビューコメントに常にこの情報を加える必要はありませんが、あなたのコメントの意図、あなたが従っているベストプラクティス、あなたの提案でコードの健康状態がどのように改善するか、などの追加説明を加える方が適切なこともあります。

ガイダンスを与える

一般に、CL を修正するのは開発者の責任であり、レビュアの責任ではありません。レビュアのあなたには、問題を解決する詳細な設計や開発者のためにコードを書くことは要求されません。

ただし、これはレビュアが開発者に手助けをしなくてもよいということではありません。一般に、レビュアには、問題点の指摘と直接的なガイダンスの提供という、両者の適切なバランスを取ることが求められます。問題点を指摘して解決方法の決定を開発者に委ねれば、開発者が学ぶ助けとなり、コードレビューをするのも簡単になります。また、開発者の方がレビュアよりもコードに親しんでいるため、より優れた解決方法を生み出すことにも繋がります。

しかし、時には直接的な指示、提案、コードそのものを提供した方が助けとなることもあります。コードレビューの1番の目的は、できるだけ最善の CL を作ることにあります。時間を経て必要なレビューをより少なくするための開発者の技術の向上は、2次的な目標です。

説明を受け入れる

あなたが理解できないコードの説明を開発者にお願いしたときは、通常は、返事としてそのコードをもっとクリアに書き換えなければなりません。場合によっては、コードにコメントを追加するのが返事として適切な場合もありますが、複雑なコードをそのままにして、その全体を説明するようなコメントであってはなりません。

コードレビューツール上にしか書かれなかった説明は、将来のコードの読み手の助けにはなりません。ツール上で説明を行うことが許されるのは、ごく限られた状況だけです。たとえば、レビュアが全然詳しくない領域について、普通のコードの読み手ならすでに知っていることを説明するような場合などです。

Next: コードレビューでの反対の扱い方