レビュー失敗事例からレビューアーが学ぶ構造的教訓

コードレビューは、ソフトウェアの品質向上とチームのスキル成長を支える重要な工程です。しかし現実には、レビューが開発を阻害し、誤解や技術的負債を助長するケースも少なくありません。本稿では、実際にありがちな失敗事例を分解し、それを通じてレビューアーが何を構造的に学ぶべきかを丁寧に掘り下げます。

第1章：レビューが炎上するプロジェクトの共通項

レビューによる摩擦が高まるプロジェクトには、いくつかのパターンがあります。典型的な構図を一つ取り上げましょう。

ケース1：粒度が揃わないレビューコメント

@Reviewer: `userService`の命名が抽象的すぎます。
@Reviewer: try-catchでエラーハンドリングをすべきです。
@Reviewer: fetchの中で何をしているのかコメントを追加してください。
@Reviewer: この関数は副作用が強すぎるように見えます。切り出せませんか？

構造的な失敗要因

• フィードバック粒度の不整合：命名、構文、設計のコメントが混在
• 文脈の欠如：目的や前提を共有せずレビューしている
• レビューア間の視点不一致：スキル差・関心領域の違いが可視化されていない

第2章：レビューの形式だけを守った「無言の承認」

ケース2：すべてのPull Requestが秒速でLGTM

@Reviewer: LGTM
@Reviewer: 👍
@Reviewer: OK

これらのコメントが続く状況では、コードの実質的な確認はされていないと推察されます。PRの平均レビュー時間が「60秒以内」といった事実がある場合、レビュー制度そのものが形骸化している兆候です。

構造的な失敗要因

• レビュー制度が評価制度と切り離されている
• レビューポイントが明文化されていない
• レビューアーの育成方針が存在しない

教訓：レビュー文化は仕組みで育てる

レビューに時間を使うことが歓迎されないチームでは、レビューの質は自然に下がります。対策としては、レビュー実施に対してチームのKPI上で意義を持たせることが必要です。たとえば、「レビュー観点ガイド」の整備や、「レビュータイムの工数カウント」などが考えられます。

第3章：曖昧な指摘が招く不信と迷走

ケース3：意味がぼやけたレビューコメント

@Reviewer: この変数名はちょっと…
@Reviewer: なんか違う気がします。
@Reviewer: もう少し綺麗にできそうですね。

教訓：レビューアーは意図を構造化して伝えるべき

上記のような指摘は、レビューイーにとって「なぜ・どこが・どう変えると良いのか」が一切伝わりません。こうした曖昧な言葉は不信の元です。

- この変数名はちょっと…
+ この変数名 `tmp` は処理内容との関連が見えにくく、他の開発者が文脈を誤解する恐れがあります。`filteredUserList`のような明示的な名称を検討してみてください。

第4章：レビューアーが設計の意図を理解しないまま指摘

ケース4：構造や意図を誤読したレビュー

function getConnection(poolSize = 3) {
  return db.connect({ max: poolSize, retry: false });
@Reviewer:
なぜretryをfalseにしているんでしょうか？通常はretryした方が安定します。
}

このような指摘は一見正論ですが、実は仕様上「retryが有害になるパターン」であることが事前に議論されている可能性があります。

教訓：レビューアーはコードの背後にある議論や文脈を知る努力をすべき

設計上の意図が議論済みかどうかは、PRテンプレート、Issueリンク、設計メモなどの情報からたどれます。レビューアーはそれを確認する責任を持つべきです。

@Reviewer: retryをfalseにしている理由を確認させてください。設計上の意図がある場合、補足情報へのリンクがあると助かります。

第5章：正しすぎるレビューがチームを壊す

ケース5：指摘が正論すぎて誰も発言できない状況

正しい指摘であっても、それが誰も反論できない口調で繰り返されると、チームの中でレビューが「権威的な行為」になります。

@Reviewer: この書き方はESLintの規約違反です。従ってください。
@Reviewer: この設計は間違っています。こうしてください。

教訓：レビューの目的は教育でも指導でもなく、コラボレーション

- この設計は間違っています。こうしてください。
+ この設計だと `再利用性` の観点でやや制限が強いかもしれません。たとえば Strategy パターンの導入を検討すると拡張性が高まりますが、どう思われますか？

第6章：責務が曖昧なコードをスルーしてしまうレビュー

ケース6：関数名やファイル名だけで内容を誤解するレビュー

レビューアーは関数名から意図を推測し、「名前が良いなら中身は大丈夫だろう」と誤認することがあります。

export function updateStatus(userId: string) {
  callExternalService(userId); // 実はここで永続処理が走る
}

@Reviewer: 名前通りの処理に見えます。特に問題ないです。

教訓：レビューアーは責務境界と副作用の両面を評価せよ

関数・メソッドは「何をしているか」と同じくらい「何をしていないか」も重要です。副作用（DB更新・IO操作・ログ送信）を明示的に扱わないレビューは、設計ミスを助長する恐れがあります。

第7章：レビューアーが「その場しのぎ」で判断を変える

ケース7：似た実装に対して違う指摘をする

@startuml

title: レビュー基準の構造化ステップ

start :レビューコメントが都度バラバラ; :指摘内容に一貫性がない; :チームから不満が出る;

if (レビュー方針の整備) then (実施) :PRテンプレート作成; :レビューポイント明文化; :コメント例をナレッジ化; else (未対応) stop endif

:レビューの一貫性向上; :開発者の信頼回復;

stop

@enduml

開発者から「先週はこれで良いって言いましたよね？」と問われた経験があるレビューアーは少なくありません。レビューの一貫性がないと、ルールそのものが信用されなくなります。

教訓：レビュー基準を構造化・標準化し、言語化する

• PRテンプレートに「レビューポイント」を列挙する
• チーム内で「レビュー方針ドキュメント」を整備
• 時間がないときでも記録を残すことで再現性を担保する

おわりに：レビューアーに求められる「構造化力」

レビューにおけるすべての失敗事例には、「抽象化・構造化の不足」が根底にあります。レビューアーは単にコードを読むのではなく、なぜそのコードが存在するのか、どういう構造的背景でその設計がなされたのかを読み取る力が求められます。

構造的教訓を言語化し、次のレビューに活かせるレビューアーこそ、チームを技術的に導ける存在と言えるでしょう。