コードレビューコメントの書き方
概要
- 優しくあれ。
- 理由を説明せよ。
- 問題を指摘するだけでなく、明確な指示と開発者が自分で決めることのバランスを取ろう。
- 複雑さを説明するだけでなく、開発者にコードを簡素化したり、コメントを追加するように促そう。
礼儀
一般的に、礼儀正しく尊重することは重要です。同時に、コードをレビューしている開発者に対して明確かつ助けになるコメントをすることも重要です。これを実践する方法の一つは、常にコードについてコメントをすることであり、開発者についてのコメントは避けることです。常にこの慣行に従う必要はありませんが、不快感や論争を引き起こす可能性のあることを言う場合には、特にこの慣行を使用するべきです。例えば：
悪い例: "なぜあなたはここでスレッドを使用したのですか？明らかに並行性から得られる利益はありません。"
良い例: "ここでの並行性モデルは、実際のパフォーマンスの利益が見当たらないまま、システムに複雑さを追加しています。パフォーマンスの利益がないため、このコードは複数のスレッドを使用するのではなく、シングルスレッドであることが最善です。"
なぜ説明するのか
上記の「良い」例について気づくことがあるでしょう。それは、コメントをする理由を開発者に理解させるのに役立つということです。レビューコメントにこの情報を常に含める必要はありませんが、時には意図やベストプラクティス、提案がコードの品質向上にどのように寄与するかについて少し説明することが適切な場合もあります。
ガイダンスの提供
一般的に、CLの修正は開発者の責任であり、リビューアの責任ではありません。 解決策の詳細な設計や開発者のためのコードの記述は必要ありません。
ただし、リビューアは無力ではあってはなりません。一般的には、問題を指摘し、直接的なガイダンスを提供する適切なバランスを取るべきです。問題を指摘し、開発者に決定を任せることは、開発者が学ぶのに役立ち、コードレビューを行いやすくすることができます。また、開発者はリビューアよりもコードに近いため、より良い解決策につながることもあります。
ただし、時には直接的な指示、提案、またはコードの提供の方が役立つこともあります。コードレビューの主な目標は、最も優れたCLを得ることです。第二の目標は、開発者のスキルを向上させ、時間の経過とともにますます少ないレビューが必要となるようにすることです。
人々は、自分がうまくやっていることを強化されることから学びます。ただし、改善できる点だけでなく、CLで好きな点もコメントしてください！例えば、開発者が乱雑なアルゴリズムを整理した、模範的なテストカバレッジを追加した、またはレビュアー自身がCLから何かを学んだなどです。すべてのコメントと同様に、なぜそのような点が好きなのかを含めて、開発者に良い慣行を続けるようにさらに促すことが重要です。
ラベルコメントの重要度
コメントの重要度をラベル付けして、必要な変更とガイドラインや提案を区別することを検討してください。
いくつかの例
Nit: これは小さなことです。技術的にはやるべきですが、大きな影響はありません。
Optional (または Consider): これは良いアイデアかもしれませんが、厳密には必要ではありません。
FYI: このCLではこれをやることは期待していませんが、将来的に考えるのに興味深いかもしれません。
これにより、レビューの意図が明確になり、著者がさまざまなコメントの重要性を優先順位付けするのに役立ちます。また、誤解を避けるのにも役立ちます。たとえば、コメントにラベルがない場合、著者はすべてのコメントを必須と解釈するかもしれませんが、実際には情報提供やオプションのコメントである場合もあります。
説明の受け入れ
もし開発者に理解できないコードの説明を求めると、通常は彼らがコードをより明確に書き直すことになるはずです。 時には、コードにコメントを追加することも適切な対応ですが、それが単に過度に複雑なコードを説明するだけでない限りです。
コードレビューツールだけで書かれた説明は、将来のコード読者にとって役に立ちません。 それらは、通常のコードの読者が既に知っていることを開発者が説明する場合など、一部の状況でのみ受け入れられます。