Code Review Best Practices: How to Review (and Be Reviewed) — cod-ai.com

私は、ソフトウェアエンジニアリングを辞めさせられそうになったコードレビューを今でも覚えています。それは2012年のこと、私はフィンテックスタートアップでの初めての仕事に就いて6ヶ月目で、私たちの決済処理モジュールの素晴らしいリファクタリングだと思って提出したばかりでした。シニアエンジニアのレビューが返ってくると、47のコメントがありました。そのほとんどは「これは間違っています」の変種で、説明はありませんでした。私は3日間コードを書き直しましたが、次のレビューでも39件のコメントが返ってきて、前のものと矛盾していました。この経験から私は重要なことを学びました：悪いコードレビューは時間を無駄にするだけでなく、チームを壊し、イノベーションを殺し、優秀なエンジニアを遠ざけます。

12年後、私は現在シニアCのSaaS会社でプリンシパルエンジニアとして働いており、8,000以上のプルリクエストをレビューし、50人以上のエンジニアに効果的なコードレビューの実践を指導してきました。コードレビュー文化を変えることで、バグ率を60％減少させ、オンボーディング時間を半分に短縮し、コードレビューを恐れられるボトルネックからチームの最も強力な学習ツールに変えられることを実際に見てきました。繁栄するチームと何とか生き延びているチームの違いは、しばしばこの単一の実践へのアプローチにかかっています。

なぜコードレビューは思っている以上に重要なのか

驚かされる数字から始めましょう。SmartBearによる2023年の研究では、コードレビューは生産に至る前に60〜90％の欠陥を見つけていることがわかりました—これは単独の自動化テストスイートよりはるかに効果的です。しかし、ほとんどの人が見逃していることがあります：コードレビューの本当の価値は単なるバグの予防ではありません。私たちのチームのメトリクスを5年間分析した結果、有効なコードレビューは時間の経過とともに複合的に効果を発揮する4つの重要な利点を提供することがわかりました。

第一に、知識の分配です。私が現在の会社に参加したとき、私たちは典型的な「ヒーロー開発者」問題を抱えていました—3人のエンジニアがコードベースの80％を理解し、それ以外の全員は狭い領域の外に触れることを恐れていました。構造的なコードレビューの実践を実施した結果、18ヶ月以内にチーム間のコード貢献の340％の増加が見られました。エンジニアたちは単にコードをレビューしていただけでなく、パターンを学び、アーキテクチャを理解し、システム全体で作業する自信を築いていました。

第二に、品質の一貫性です。明確なレビュー基準を設定する前は、私たちのコードベースはさまざまなスタイル、パターン、品質レベルのパッチワークでした。どのチームがどのモジュールを書いたのか、見ただけでわかることができました。レビュー文化の変革後、静的解析スコアは73％改善され、何よりも新しいエンジニアは初めての1ヶ月間にコード品質の期待について4倍も自信を感じると報告しました。

第三に、スケールでのメンターシップです。私はチームのすべてのエンジニアを個別に指導することはできませんが、思慮深いコードレビューを通じて、同時に何十人もの人々に洞察を共有することができます。ある特定の競合パターンを選択した理由についてのよく説明されたレビューコメントは、我々の内部ドキュメントで89回参照され、繰り返しの説明の膨大な時間を節約しました。

第四に、最も過小評価されがちな点：コードレビューはチームの健康のための早期警告システムです。レビューのターンアラウンドタイムが急増したとき、コメントスレッドが加熱したとき、特定のエンジニアが参加しなくなったとき—これらは炭鉱のカナリアです。私はコードレビューのパターンに注意を払うことで、燃え尽き、対人関係の対立、アーキテクチャ的な意見の相違を爆発する何週間も前に見つけ出しました。

レビュー担当者のマインドセット：正しさではなく

私がシニアエンジニアとしての最初の年に学んだ不快な真実は、技術的に正しいことが良いコードレビュアーになるわけではないということです。私はバグを見つけ、パフォーマンスの問題を特定し、ベストプラクティスを遵守していました—それでも私のチームの士気は急降下していました。私のレビュー承認率は12％で、88％のPRに変更が必要でした。私は高い基準を維持していると思っていました。マネージャーは私がボトルネックを生み出し、人々にコードを提出することを恐れさせていると考えていました。

「悪いコードレビューは時間を無駄にするだけでなく、チームを壊し、イノベーションを殺し、才能のあるエンジニアを遠ざけます。」

変化が訪れたのは、コードレビューを判断ではなく会話と見なすようになったときです。「ここが間違っています、依存性注入を使うべきです」ではなく、「テスト可能性について懸念があります—依存性注入を考慮したことはありますか？もしそれが不明な場合、一緒に作業しましょう」と書くようになりました。技術的内容は同じでしたが、フレーミングが全てを変えました。2ヶ月以内に、私の承認率は67％に上昇しましたが、より重要なのは、エンジニアが提出前に質問を安心してできるようになったため、初回の提出の品質が40％向上したことです。

私が今教えているマインドセットは、次のようなものです：レビュー担当者のあなたの仕事は、著者よりも賢いことを証明することではありません。あなたの仕事は、高品質のコードをリリースしながら、著者をより良いエンジニアにすることです。それは、批判する前に文脈を理解し、要求する前に質問をし、問題に対してしばしば複数の有効な解決策があることを認識することを意味します。

私が使用しているメンタルフレームワークは「レビューにおける3つのレベルのフィードバック」と呼ばれています。レベル1の問題は客観的な問題です：バグ、セキュリティの脆弱性、確立されたチーム基準の違反。これらは変更が必要です。レベル2の問題は強い提案です：パフォーマンスの懸念、保守性の改善、より良いパターン。これらは議論に値します。レベル3の問題は個人的な好みです：変数の命名、コードの整理、スタイル上の選択。これらは稀であり、明確に非ブロッキングとしてラベル付けされるべきです。

問題は、ほとんどのレビュワーがすべてをレベル1と見なすことです。インデントの好みや変数の命名について18のコメントがあり、実際のレースコンディションに対処したのはわずか2つのコメントしかない20コメントのレビューのスレッドを見たことがあります。すべてが重要であれば、何も重要ではありません。私は今、レビューの中で大体70％がレベル1、25％がレベル2、5％がレベル3になるよう目指しています。もし私が2つ以上のレベル3のコメントを書いていることに気づいたら、実際にコードを改善しているのか、それとも自分の好みを押し付けているだけなのかを考えます。

効果的なレビューコメントを書く技術

私は、フィードバックを効果的にするものと混乱や対立を生むものを理解するために、数千のコードレビューコメントを分析しました。違いはしばしば構造と具体性に関わってきます。「これはスケールしない」というコメントは技術的にはフィードバックですが、無駄です。問題を説明せず、解決策を提案せず、著者が学ぶのを助けません。それを「このO(n²)ループは、10K以上のレコードに達すると問題になります（Q3にそのように予測しています）。ここでO(n)のルックアップのためにハッシュマップを使用することを検討してください。これが支払い処理に使用した似たようなパターンです：[リンク]。」と比較してみてください。