レビューで好みの指摘と品質リスクをどう切り分けるか

コードレビューでは、正しい指摘と好みの指摘が混ざりやすい。
たとえば、次のようなコメントは現場でよく見る。

@Reviewer: この書き方は好みではないので直してください。

このコメントは危うい。
本当に品質リスクがあるのか、チームルールなのか、単なる個人の好みなのかが分からない。

レビューアーがまず行うべきなのは、指摘を書く前に
これはブロックすべき品質リスクか、任意の改善提案かを切り分けることである。

この記事では、レビューにおける好みと品質リスクの線引きを、実務で使える判断軸として整理する。

なぜ切り分けが必要なのか

好みの指摘を強く書くと、レビューは摩擦を生む。
逆に、品質リスクを弱く書くと、重要な問題が流れてしまう。

どちらも避けたい。

• 好みを必須修正にすると、チームの速度が落ちる
• 品質リスクを任意提案にすると、障害や保守負債が残る
• 指摘強度がぶれると、レビューイーが優先順位を判断できない
• レビューアーごとに基準が違うと、チームルールが育たない

レビューで重要なのは、指摘数ではない。
指摘の強度がリスクに合っていることである。

まず分けたい3分類

1. 品質リスク

バグ、障害、セキュリティ、データ不整合、運用事故につながるものは品質リスクである。
これはマージ前に止める理由になる。

@Reviewer: この処理は決済API呼び出しにリトライを入れていますが、冪等性キーがありません。通信失敗時に二重決済になる可能性があるため、マージ前に重複防止方針を入れてください。

このコメントは強くてよい。
理由と失敗シナリオが明確だからである。

2. チームルール

formatter、lint、命名規約、ディレクトリ構成など、チームで合意済みのルールは個人の好みではない。
ただし、ルールへの参照を示すとよい。

@Reviewer: このファイルは既存ルールでは `features/orders` 配下に置く方針です。関連するAPI、hook、型定義を同じfeature境界に寄せるため、配置を合わせてください。

チームルールは、背景が説明できるほど納得されやすい。
単に「ルールなので」だけで終わらせないほうがよい。

3. 個人の好み・任意提案

どちらでも成立するが、読みやすさや一貫性の観点で提案したいものもある。
これは強く書きすぎない。

@Reviewer: ここは現状でも読めますが、条件が増えるなら早めに関数名へ意図を出す案もあります。必須ではありませんが、`canSubmitOrder` のようにすると判定目的が残りやすいです。

任意提案は、受け手が採用しない選択肢を持てるように書く。
これだけでレビューの摩擦はかなり減る。

判断軸1：壊れるか、迷うだけか

最初の判断は、放置したときに壊れるかどうかである。

レビューコメントを書く前に、この表に当てはめるだけでも強度のぶれは減る。

判断軸2：根拠をチームで共有できるか

指摘の根拠を、他のレビューアーも同じように説明できるかを考える。

• 仕様書に書いてある
• 既存コードの方針と一致している
• 運用上の事故を防ぐ理由がある
• テストで検証できる
• チームルールとして明文化されている

これらがあるなら、好みではなく共有可能な判断に近い。

@Reviewer: このエラーは呼び出し元でリトライ判定に使われるため、単なる `fmt.Errorf` ではなく判定可能なエラー型にしてください。既存の外部API呼び出しでも同じ方針になっています。

根拠が共有できるコメントは、議論になっても前に進みやすい。

判断軸3：代替案が複数あるか

解決策が複数ある場合、レビューアーの提案を唯一解のように書かない。
目的を固定し、手段は相談にする。

@Reviewer: ここで重要なのは、失敗時に部分更新が残らないことです。実装案としてはトランザクションに寄せる、または更新単位を分ける方法があります。どちらの方針にするか確認したいです。

このコメントは、目的を明確にしつつ、実装者の設計判断を残している。
レビューで常に細部まで指定する必要はない。

好みの指摘を書きたいとき

好みの指摘を完全になくす必要はない。
ただし、次の条件を満たすときだけにしたい。

• 既存コードとの一貫性が崩れている
• 将来の読み手にとって認知負荷が上がる
• チームで何度も同じ議論が起きている
• 任意提案であることを明示できる

@Reviewer: 必須ではありませんが、このプロジェクトではboolean関数を `is` / `has` / `can` で始める例が多いです。既存コードに合わせるなら `canRetry` のほうが読みやすいかもしれません。

このように書けば、好みの押し付けになりにくい。

チームルールへ育てる

同じ好みの指摘が何度も出るなら、それは個人の好みではなく、チームルール候補かもしれない。
その場合、PR上で毎回強く言うより、ルール化を提案したほうがよい。

@Reviewer: この命名方針は今回だけでなく複数PRで議論になっているため、レビューコメントで都度判断するより、チームの命名ルールとして短くまとめたほうがよさそうです。

レビューはルールを押し付ける場ではない。
しかし、繰り返し発生する判断をチーム資産に変える場ではある。

チェックリスト

まとめ

レビューで好みを完全に消すことはできない。
しかし、好みの指摘と品質リスクを同じ強度で扱うと、レビューは不安定になる。

レビューアーは、コメントを書く前に
これは壊れるリスクなのか、チームルールなのか、任意提案なのかを切り分けたい。

その切り分けができるほど、レビューコメントは強くも柔らかくも適切に書ける。