レビューコメントの書き方
要約
- コメントは丁重に
- 理由を説明してください
- 問題の指摘に加えて明確な方向性を示すことと、開発者本人に決定を委ねることをバランス良く行ってください
- 複雑なコードを見つけたらそれを説明してもらうだけで終わらせず、コードをシンプルにしてもらうとかコードにコメントを追加するよう開発者に勧めてください
礼儀正しさ
一般論として、あなたがレビューしているコードの開発者にコメントを送るとき、明確で有益な内容であることもちろん大切ですが、礼儀正しく敬意を払った書き方であることも大切です。 それを実践する一つの方法は、必ずコードについてコメントし、開発者本人についてコメントしないよう心がけることです。 この慣例に杓子定規に従う必要はありませんが、相手を傷つけたり怒らせたりするかもしれない繊細な内容を書くときには必ずそうするようにしてください。 以下はその例です。
悪い例「並行処理にしても明らかにメリットがないのに、どうしてあなたはスレッドを使ったのですか？」
良い例「見たところ、ここで使った並行処理モデルは実際にはパフォーマンス上のメリットがないまま、ただシステムを複雑にしています。パフォーマンス上のメリットがないので、複数スレッドを使わずにシングルスレッドのコードにするのが最善です」
「なぜ」を説明する
上の「良い例」でひとつお気づきでしょうが、あなたが書いているコメントの「理由」を開発者が理解することは有益です。 レビューコメントに必ずこの情報を含める必要があるかというと、そうではありませんが、それが適切な場合があります。 そういうときには、コメントの意図についてもう少し詳しく説明したり、あなたが参考にしているベストプラクティスを教えたり、あなたの提案がどのようにコードの健康状態を良くするのかを解説したりしてください。
指示を与える
CL を修正するのは一般的に開発者の責任であって、レビュアーの責任ではありません。ソリューションの詳細な設計をしたり開発者の代わりのコードを書いたりする仕事はレビュアーに求められていません。
とはいえ、レビュアーは手助けしないでただ突き放せばよいということではありません。 一般にレビュアーは、問題を指摘することと指示を直接与えることを適度にバランス良く行うべきです。 問題を指摘して決定を開発者本人に任せることは、しばしば開発者が自分で学ぶ機会になりますし、コードレビューが楽になります。 また、開発者はレビュアーよりもコードを間近で見ているので、開発者に任せるほうが良いソリューションになることもあります。
その一方で、直接的な指示や提案や、ときにはコードを見せることがさらに有益になる場合もあります。 コードレビューの主要な目的は CL の品質をできる限り良くすることです。 第二の目的は、開発者のスキルを向上させ、長期的にレビューを不要にすることです。
説明を受け入れる
あなたが理解できないコードを開発者に説明してもらうのは、多くの場合、コードをもっと明確に書き直してもらうほうが良い結果になります。 ときには、複雑すぎるコードを説明してもらうだけでなく、コードにコメントを追加するのも適切な応答になります。
コードレビューツールの中に説明を書き残しても、将来そのコードを読む人にとって役に立ちません。ツールにコメントを残すのが受け入れられるケースは、限られた状況だけです。たとえば、あなたがあまり詳しくない分野のレビューをしていて、通常そのコードを読む開発者はすでによく知っているような情報を説明してもらうときには、ツールにコメントを残せば十分です。