レビューコメントで修正理由が伝わらない指摘をどう設計するか

コードレビューでは、技術的には正しい指摘でも、受け手に伝わらないことがある。
典型的なのは、次のようなコメントだ。

@Reviewer: この関数は分けてください。

このコメントは短い。
しかし、なぜ分けるべきなのか、どの単位で分けるべきなのか、分けない場合に何が危ないのかが分からない。

レビューアーが書くべきなのは、単なる修正命令ではない。
判断理由が再利用できるコメントである。

この記事では、レビューコメントを「意見」ではなく、
修正理由、影響範囲、判断基準を伝える設計物として扱う観点を整理する。

まず避けたいコメント

@Reviewer: ここは責務が多いので分けてください。

一見すると、責務分離を指摘しているので良さそうに見える。
だが、このコメントだけでは受け手が次を判断できない。

• どの責務が混ざっているのか
• どこまで分ければ十分なのか
• 今回の変更でなぜ問題になるのか
• 好みの指摘なのか、保守リスクなのか

レビューコメントは、短ければよいわけではない。
短くても判断軸が残るかが重要である。

なぜ修正理由が必要なのか

修正理由がないコメントは、レビューイーに「作業」だけを渡す。
修正理由があるコメントは、レビューイーに「判断」を渡す。

この差は大きい。

• 同じ問題を次回自分で避けられる
• 反論や代替案を出しやすくなる
• チーム内で判断基準が蓄積される
• レビューアーの好みと品質リスクを分けられる

レビューの目的は、差分を通すことだけではない。
次の差分が少し良くなる判断材料を残すことも含まれる。

コメントに入れたい3つの要素

1. 何が問題か

まず、問題を構造として示す。

@Reviewer: この関数では入力検証、DB更新、通知送信が同じ制御フローに入っており、失敗時の扱いが読み取りにくくなっています。

ここでは「長い」ではなく、「入力検証、DB更新、通知送信が混ざっている」と具体化している。
受け手は、どこを見ればよいか分かる。

2. なぜ危ないか

次に、リスクを説明する。

@Reviewer: 通知送信が失敗したときにDB更新まで失敗扱いにするのか、通知だけ再試行するのかがコードから判断できません。

この一文があると、指摘は好みではなく設計リスクになる。

3. どう直す方向があるか

最後に、修正の方向を示す。

@Reviewer: DB更新の成功単位と通知の再送責務を分け、通知はoutboxや後続ジョブに切り出す構成を検討してください。

具体案は1つでよい。
重要なのは、レビューイーが最初の一歩を踏み出せることだ。

悪いコメントと良いコメントの比較

悪い例

@Reviewer: この処理は複雑なので整理してください。

このコメントでは、「複雑」の中身が分からない。
修正後に何を満たせばよいかも分からない。

良い例

@Reviewer: この関数では、リクエスト値の検証、在庫更新、決済API呼び出し、メール送信が1つの成功単位に見えています。決済API成功後にメール送信が失敗した場合、注文を成立扱いにするのか再試行するのかがコードから読めません。まずDB更新と外部副作用の境界を分け、失敗時の再試行責務を明示してください。

このコメントには、次が含まれている。

• 混ざっている責務
• 危険な失敗シナリオ
• 修正の方向
• レビューアーの判断基準

長さは増えるが、議論の往復は減りやすい。

コメント強度を明示する

レビューコメントでは、必須修正なのか、提案なのかが曖昧になりやすい。
ここが曖昧だと、レビューイーは優先順位を誤る。

@Reviewer: これは障害時に二重決済につながる可能性があるため、マージ前に修正が必要です。

@Reviewer: この命名は現状でも読めますが、将来条件が増えるなら `isRetryable` のように判定理由が分かる名前にすると保守しやすくなります。

前者はブロッキング、後者は提案である。
コメント本文でその違いを表現するだけで、レビューの進行はかなり安定する。

レビューコメントの組み立て方

迷ったときは、次の順番で書くとよい。

1. 対象箇所で何が起きているか
2. それがどのリスクにつながるか
3. どの判断基準で止めているか
4. どの方向に直すとよいか

@Reviewer: `handleSubmit` で入力検証、API呼び出し、画面遷移、通知表示が直列に書かれており、失敗時の表示責務が混ざっています。API失敗時に画面遷移してよいのか、通知だけ出すのかが読み取れません。送信処理とUI反映を分け、成功・失敗ごとの画面責務を明示してください。

この形なら、レビューイーは単に「分ける」だけでなく、何を分けるべきかを判断できる。

避けたい脱線

修正理由を説明するとき、長く書きすぎて論点がぼやけることもある。
レビューコメントでは、次の脱線を避けたい。

• 一般論だけを書く
• 自分の好みを正解のように書く
• 複数の問題を1コメントに詰め込む
• 具体的な差分から離れて説教になる

コメントは教育資料ではなく、差分に対する判断である。
説明は必要だが、対象コードに接続している必要がある。

チェックリスト

まとめ

レビューコメントは、修正依頼であると同時に判断基準の共有でもある。
「直してください」だけでは、作業は伝わっても理由は残らない。

レビューアーは、指摘の中に
問題の構造、危険な理由、修正方向を入れることで、次のレビューにも使える判断を残せる。