コードレビュー演習：ピアレビューを活用して分析力と技術的判断力を養う方法

開発者が、チェックアウトサービスに割引計算機能を追加するプルリクエストを作成しました。テストはパスし、差分も短いため、レビュー担当者は2分で「LGTM」と承認しました。3か月後、チームメイトが同じ機能を変更する必要が生じ、価格設定ルール、丸め処理、データベースアクセスが1箇所に混在していることを発見しました。何が許容される動作なのか、誰も確信を持って言えません。

これはあくまで例示であり、実際に発生した事例ではありません。ピアコードレビューが学習活動として機能している場合、どのような成果が期待できるかを示しています。つまり、レビュー担当者が妥当な変更点を見抜き、まだバグではないものの懸念事項を特定し、それを作成者が対処できる形で説明できる、という成果です。

このガイドは、エンジニアリングイネーブルメントリーダーとエンジニアリングマネージャー向けです。レビュー担当者が自然にスキルを習得することを期待するのではなく、意図的にスキルを育成するコードレビュー演習の設計方法を示します。パフォーマンスの問題、診断すべきギャップ、準備と練習の構成方法、具体的な例、そしてスキルが実際のレビューに活かされるかどうかの確認方法について解説します。使用する前に、すべてのケース、欠陥、および評価基準について、シニアエンジニアに検証してもらってください。

コードレビュー演習とは何ですか？

コードレビュー演習とは、開発者が事前に用意された変更内容をレビューし、発見した内容とその重要性を説明し、その説明の質についてフィードバックを受けるという、構造化された練習課題です。これは、チームが日常的に行っているレビューとは異なります。変更内容は事前に選定され、その内容に含まれる懸念事項も既知であり、目的は変更内容をリリースすることではなく、レビュー担当者のスキル向上にあります。

クイック事実

1. パフォーマンス上の問題点を説明する

まず、課題を1文で説明しましょう。変更点が与えられた場合、レビュー担当者は発見した内容、その重要性、そして著者がそれに対してどのような対応を取るべきかを説明します。「説明する」という点が重要です。問題点を見つけることはスキルの半分に過ぎません。異なる見解を持つ同僚が理解し、検討し、行動に移せるように説明することが、残りの半分なのです。

現代のコードレビューに関する研究は、バグ探しだけにとどまらない視点を持つことの重要性を示唆しています。マイクロソフトで行われた調査で、バッケリとバードは開発者とマネージャーを対象に観察、インタビュー、アンケート調査を実施しました。その結果、欠陥の発見は依然としてレビューの主な動機であるものの、レビューは人々が期待していたほど欠陥に焦点を当てたものではないことが分かりました。また、知識共有、チームの意識向上、代替ソリューションの提案など、その他のメリットも得られており、研究者らはコードと変更内容の理解がレビューの重要な側面であると述べています（Bacchelli and Bird, ICSE 2013）。これはある企業のチームを対象とした研究なので、理解を重視した設計を行うための参考として活用してください。自社のチームに当てはめるものではありません。

Googleが公開しているレビュー基準も同様の方向性を示しています。レビュー担当者には、たとえ完璧でなくても、コード全体の健全性が確実に向上する変更は承認するよう促し、レビューは開発者に新たな学びをもたらすため、学習に役立つコメントは歓迎すると述べています（Googleエンジニアリングプラクティス）。どちらの資料も、レビューを判断を下し、伝達する場として説明しています。皆さんの演習は、まさにこのことを練習するものであるべきです。

2. 学習と状況のギャップを診断する

その課題を、現在受講しているプログラムで実施・評価されている内容と比較してください。

1. 現在の実践は、実際の課題に基づいているか？ 新しいレビュー担当者がスタイルガイドを読んでから実際のプルリクエストをレビューすることで学習する場合、彼らは間違いを恐れることなく実際の作業で練習することになります。評価がレビューのマナーに関するクイズである場合、それはルールを覚えているかどうかを測定するものであり、変更に適用する能力を測定するものではありません。
2. 認知的な要求とは何ですか？ 改訂版ブルームの分類法では、設計が健全かどうかを判断し、そのトレードオフを比較検討することは分析と評価のレベルにあり、より良い構造を提案することは創造のレベルにあります。演習で「このコードは何をするのか？」としか問わない場合、理解の段階で止まってしまいます。 学習活動をブルームの分類法に合わせる アクティビティをレベルに合わせて調整する方法を示します。
3. スキル以外の何かが妨げになっているのでしょうか？ レビュー時間、ツール、担当者、チームの規範を確認してください。レビュー担当者がプルリクエスト1件につき5分しか時間をかけられない場合、どんなに工夫しても思慮深い説明は生まれません。著者がすべてのコメントを批判と受け止める場合、レビュー担当者は指摘を弱め、最終的には何も言わなくなってしまうでしょう。これらの原因を、解決できる担当者に報告してください。

3. デザインの準備、実践、フィードバック

各段階にそれぞれ異なる役割を与える。

準備。レビュー担当者が作業を開始する前に必要なものを確認してください。チームのレビューチェックリスト、そのチェックリストが依拠する設計原則、ツールにおける差分表示の読み方などです。この作業は各​​自のペースで短時間で行ってください。リコールチェックは前提条件を確認するだけであり、レビュー担当者がレビューできる能力があることを証明するものではありません。

練習してみましょう。あらかじめ用意した変更に、さまざまな種類の懸念事項を少数含めます。例えば、正当性に関するバグ、冒頭の例にある責任の混在といった保守性の問題、不明瞭な名前やテストの欠落、そして問題のないコードなどです。レビュー担当者に、どのようなコメントを残すか、懸念事項の優先順位、そしてどのような追加情報が必要かを尋ねます。CodeRefinery の実践レッスンでは、その形式が示されています。参加者は、小さなタイプミスと大きな間違いを含むプルリクエストを開き、それを同僚としてレビューします ( CodeRefinery、「コードレビューの実践」)。慣習やトレードオフが現実的になるよう、自分のコードベースから独自のレ​​ッスンを作成しましょう。

フィードバック。レビュー担当者が下した決定と関連付けましょう。「丸め誤差に気付いたものの、コメントには『これはおかしい』とだけ書かれていて、どの入力が問題を引き起こしているのかが書かれていない」という方が、「4件中2件見つかりました」よりも役立ちます。

リアルタイム入力と非同期レビュー、どちらが良いでしょうか？リアルタイム入力は、懸念事項が曖昧な場合に最も効果を発揮します。レビュー担当者は、上級エンジニアがなぜその問題を提起するのか、あるいは見過ごすのかを説明するのを聞くことで、理解を深めることができます。非同期レビューは、コメントを注釈付きの専門家レビューと比較する程度であれば十分です。

4. 現実的な例題に取り組む

例示です。エンジニアリングマネージャーは、使用前に事例と回答基準を検証する必要があります。

事例：チェックアウトサービスに割引計算機能を追加する変更。この変更はテストに合格する。1つの関数内で、パーセンテージ割引と固定割引を適用し、結果を四捨五入し、データベースに書き込み、イベントを送信する。テストは1つだけで、単一のパーセンテージ割引のみに対応する。

課題：レビュー担当者は、残したいコメントを記入し、懸念事項を優先順位付けし、承認する前に知っておくべきことを述べます。

最初の試み。「問題なさそうだ、テストは合格。分割した方がいいかも？」レビュー担当者は何か気づいたものの、それが何なのか、なぜ重要なのか、どうすべきなのかを述べていない。著者はこれに対して何も行動を起こせない。

フィードバックと再検討。ファシリテーターは、「この機能に将来変更を加えると、どのような不具合が発生するリスクがありますか？承認する前に、作成者に何を追加してもらいたいですか？」と質問します。再検討では、それぞれの懸念事項について、理由と提案を添えて具体的なコメントを求めます。

より強い提案です。「この関数は 2 種類の割引を適用し、丸め、保存してイベントを発行するため、丸めを変更すると、保存する内容と発行する内容が同時に変更される可能性があります。価格設定ルールを、単独でテストできる純粋な関数に移動するようにお願いします。単一のテストでは、パーセンテージ割引しかカバーしていません。固定割引と、合計がゼロになる注文をお願いします。合計がゼロのときにイベントが発生するように意図されているかどうかわからないので、作者に質問します。」このコメントでは、懸念事項を明記し、理由を示し、具体的な提案を行い、レビュー担当者が知らないことを述べています。

5．能力を評価し、移転計画を策定する

能力の証拠は、レビュー担当者がまだ見たことのない新しい変更に対するパフォーマンスです。調査結果の正確さと説明の有用性を評価します。シンプルな評価基準では、各基準につき0～2の尺度を使用します。

評価基準：0は欠落またはサポートなし、1は関連する項目が欠落している部分的、2は合意された基準に照らして完全かつ正当化されていることを意味します。重大なエラーは個別に定義してください。例えば、データ損失リスクのある変更を承認した場合など、全体的なスコアが高くても重大なエラーが隠蔽されないようにしてください。評価基準はエンジニアリングマネージャーと調整してください。この評価基準はあくまでも提案段階のものであり、検証済みの準備基準ではありません。採点理由の詳細については、「有用なフィードバックを伴うインタラクティブな実践の設計ガイド」を参照してください。

移行計画を立てましょう。演習後、数週間後に同じ基準を用いて、レビュー担当者の実際のレビューのサンプルを確認します。トレーニング前に取得したベースラインと比較し、対象者とタイミングを事前に定義します。演習の効果を評価する前に、新しいレビューツールや人員配置の変更など、同じ期間に発生したその他の変更点も考慮してください。

6. AhaSlidesを使って、ライブまたは自分のペースで演習を実施する

この演習はワークショップ形式で実施することも、レビュー担当者に各自で取り組んでもらうこともできます。ライブセッションでは、準備した変更内容を示し、インタラクティブなスライドを使って議論を進めてください。

1. 答えを選ぶ 「どの懸念事項を最初に提起しますか？」という質問に対し、あらかじめ提示された懸念事項を選択肢として示します。自分の順位を明かす前に、提示された懸念事項の分布を示してください。
2. オープンエンド 「あなたが残したいコメントを記入してください」という項目です。レビュー担当者は自分の表現を他の人の表現と比較することができ、そこで説明能力が発揮されます。
3. 評価スケール 「これはどの程度深刻な問題か？」という問いに対して、グループ内で判断の相違点を確認し、その理由について話し合うことができるようにするためです。

参加できないレビュー担当者は、同じ手順を各自のペースで進めることができ、各回答の後には注釈付きの専門家レビューが表示されます。コードの実行、統合、またはAI機能に関する主張は、ご自身の資料で試すまでは未確認情報として扱ってください。

AIが生成したコードのレビュー担当者を育成する場合は、AI生成コードのレビューに関するトレーニングガイドも併せてご覧ください。そちらの記事では、生成された出力の監査について説明しています。この記事では、人々が互いの作業をどのようにレビューし、発見した問題点をどのように説明するかについて解説します。

残る可能性のある制約

• レビューの時間です。 思慮深いコメントは「LGTM」よりも時間がかかるが、締め切りが迫っているため、簡潔な表現が求められる。
• チームの規範。 フィードバックが個人的な批判と受け取られた場合、レビュー担当者は評価を和らげたり、評価を取り下げたりするだろう。
• 事件報道。 ある演習では、いくつかの懸念事項が明らかになった。点数は、レビュー担当者の判断力を一般的に表すものではない。
• 転送。 ワークショップでのパフォーマンスは、混雑した状況でのパフォーマンスとは異なるため、実際のレビューも確認してください。

これらの点を早めにスポンサーに伝え、個別の修正計画を立てましょう。演習は、レビュー担当者が理解し説明できる内容を向上させるものです。しかし、時間や基準を作り出すものではありません。

よくある質問

コードレビュー演習とは何ですか？

これらは、開発者が既知の懸念事項を含む変更内容をレビューし、コメントを記述し、正確性と有用性に関するフィードバックを得るための、準備された練習課題です。目的は、変更内容をリリースすることではなく、レビュー担当者のスキルを向上させることです。

レビュー担当者の判断力が向上したかどうかをどのように評価しますか？

彼らがまだ見たことのない新しい変更点を提示し、合意された基準に基づいて調査結果と説明を評価します。その後、数週間後に実際のレビューのサンプルを確認します。レビュー規則に関するクイズは、前提条件を確認するためだけのものです。

ピアコードレビューは主にバグを見つけることが目的ですか？

欠陥の発見は依然として主な動機付けとなっているが、マイクロソフトのある研究では、レビューは予想よりも欠陥に関するものではなく、知識共有やチームの意識向上にも役立っていることが分かった。欠陥数だけでなく、説明や理解度も評価する設計演習が有効である。

どこから始めれば

チームが頻繁にレビューする変更の種類を1つ選びます。パフォーマンスステートメントを作成し、上級エンジニアに3つか4つの懸念事項を盛り込んだ変更を1つ準備してもらい、0～2のスケールと重大なエラーのリストを含む3つの評価基準からなるルーブリックを作成します。少人数のグループでパイロットテストを実施し、その後の実際のレビューを基準値と比較します。

レビュー演習をチーム内で実際に実施し、その後各自のペースで再利用する方法を知りたい場合は、AhaSlides をご覧ください。