レビューコメントは、コードの書き手を評価する文章ではありません。変更を安全で理解しやすい状態へ近づける会話です。
コメントの4要素
観察: 失敗時にも200を返しています。
影響: 呼び出し側が成功と失敗を区別できません。
提案: 入力エラーは400で返す案はどうでしょうか。
確認: 既存クライアントが200を前提にしていないか確認したいです。
強さを示す
- 必須: セキュリティ、データ破損、仕様違反
- 提案: 保守性や読みやすさの改善
- 質問: 意図や前提の確認
- 細部: 表記や好み
重要度が分かると、書き手は対応順を判断できます。
人ではなく変更を見る
「理解していない」ではなく「この名前から単位を判断できない」と書きます。断定できない時は質問にします。
良いレビューは、直す場所だけでなく、なぜ直すかを次の変更にも残します。
ケーススタディ：注文APIのレビュー
注文作成APIの差分で、在庫確認後に決済を行い、その後で在庫を減らしているとします。単に「競合に弱いので直してください」と書くと、どの競合を指すのか、どこまで直せば承認されるのかが分かりません。観察として「同じ商品の二つの要求が在庫確認を同時に通過できます」、影響として「在庫一件でも二件の決済が成立する可能性があります」、重要度として「データ整合性に関わるため必須」、提案として「在庫確保を条件付き更新にし、更新件数がゼロなら決済へ進まない方法を検討できます」と分けます。
ここで提案は唯一の正解として押しつけません。既存の予約機構や決済取消の契約を実装者が知っているかもしれないため、「同時要求を扱う既存方針はありますか」と確認を添えます。良いコメントは、問題が再現する条件と承認条件を示します。悪いコメントは「危険」「分かりにくい」「普通はこうする」のように、書き手の評価だけを残します。
コメントを書く判断手順
まず差分で観測できる事実と、自分の推測を分けます。次に、利用者、データ、保守、性能のどこへ影響するかを一つ具体化します。仕様違反や障害につながるなら必須、複数の妥当な設計があるなら質問、動作を変えない好みなら細部として強さを付けます。その後、最小の再現例、関連仕様、既存テストのどれかを根拠にします。最後に、何が確認できればスレッドを解決できるかを書きます。
レビュー品質の観測
レビュー後には、コメント数の多さではなく結果を見ます。必須と提案が区別されていたか、実装者が追加質問なしで問題を再現できたか、修正後のテストが指摘したリスクを覆っているかを確認します。同じ論点が何度も往復する、好みの議論で承認が止まる、修正したのに完了条件が分からない状態は失敗の兆候です。
一方、コメントが一つもないことも品質の証明にはなりません。認証境界、失敗経路、既存仕様との互換性など、差分の危険度に応じた観点を確認した記録が必要です。レビューが長引いた場合は人の能力ではなく、PRが大きすぎないか、仕様が本文にないか、自動テストで代替できる反復指摘がないかを振り返ります。
よくある誤解：丁寧さと曖昧さは違う
「柔らかく書けばよい」と考えて、仕様違反まで「気がします」にすると優先度が伝わりません。認可漏れやデータ破壊は必須修正と明示し、根拠となる要件やテストを添えます。逆に、命名の好みを「必ず直してください」と書くと、動作上の問題と同じ重さに見えます。指摘の強さは口調ではなく、放置した場合の影響で決めます。
「提案コードまで書けば親切」も常に正しくありません。提案が唯一の解でない時は、守るべき条件を先に示し、実装者の設計理由を尋ねます。「このキャッシュは利用者ごとに分離されますか。共有されるなら他人の結果が見えるため修正必須です」のように、観測できる危険と解決条件を結びます。
| コメントの対象 | 書く中心 | 解決の確認 |
|---|---|---|
| 仕様違反 | 期待結果と現在の差 | 受け入れテスト |
| セキュリティ | 攻撃条件と露出する資産 | 負のテストと権限境界 |
| 可読性 | 読み違える具体箇所 | 名前または構造の再確認 |
| 質問 | 不明な前提 | 実装者の説明か資料 |
| 細部 | 任意であること | 対応不要でも解決可能 |
動作確認：コメントだけで次の行動が決まるか
投稿前に、差分を知らない人がコメントを読み「何が問題か」「なぜ影響するか」「何を確認すれば解決か」を答えられるか確認します。行番号だけに依存せず、対象の条件や入力を短く含めます。修正後は、提案どおりの形になったかではなく、最初に示したリスクがテストや説明で解消したかを見ます。
レビュー往復回数だけでなく、必須と任意の取り違え、再質問が必要だった割合、コメントから追加されたテストを振り返ります。人格を主語にした表現、根拠のない断定、解決条件のない長文が残っていれば、具体的なコメントを題材に直します。レビューの完了条件はレビュアー案への服従ではなく、指摘した不確実性の解消です。
まとめ
伝わるレビューコメント：指摘・理由・提案を分けるで大切なのは、用語を単独で暗記することではありません。期待、観測、差分、仮説、操作、結果を順に残し、テーマに合う証拠で判断します。小さく確認し、再現できる説明を残すことが、修正と学習の両方を次へつなげます。
参考リソース
短くても、根拠と解決条件を省略しません。
大きな設計問題を一つの行へ大量に書くと、局所修正で解決できるように見えます。差分全体に関わるなら総評へ置き、具体的な行コメントから参照します。互いに独立した問題はコメントを分け、片方を直した時にもう片方まで解決扱いにならないようにします。
コメントを解決するのは実装者だけの仕事ではありません。レビュアーは回答や新しい差分を読み、当初の懸念が消えたか確認します。前提を誤解していたなら、そのことを認めてコメントを閉じます。議論が長くなる時は同期会話へ切り替えても、最終的な決定理由はPRへ戻します。
教育目的のレビューでは、すべての改善点を一度に指摘しません。今回の課題目標に直結する一、二点を優先し、学習者自身が修正理由を説明できる余白を残します。ただし秘密情報の混入や認可漏れは学習段階でも省略せず、公開前に止めます。
コメントを組み立てる具体例
注文APIの差分でuserIdをリクエスト本文から受け取って検索していた場合、「危ないです」だけでは不足です。「必須: 本文のuserIdを信用すると、ログイン利用者が別IDを指定して他人の注文を読めます。認証コンテキストのIDで絞り、別利用者IDを指定しても取得できない統合テストを追加してください」と書けば、指摘、理由、解決条件が揃います。
同じ差分で変数名がdataだった時は、セキュリティ指摘と同じ強さにしません。「任意: ここは注文要約なのでorderSummaryだと後続の配送情報と区別しやすそうです」と示します。既存規約があるならリンクを根拠にし、なければ好みとして扱います。
質問コメントは、知識試験ではなく前提の確認です。「なぜこうしたのですか」だけでは尋問に見えるため、「再試行で二重作成されないよう、冪等キーは上流で付与される前提でしょうか。前提がなければこの層で必要です」と、自分が懸念する分岐を添えます。実装者の回答で前提が確認できれば、コード変更なしで解決して構いません。
レビュー後には、コメントが集中した種類を振り返ります。毎回権限条件が抜けるならチェックリストや共通テストを改善し、細かな書式指摘が多いなら自動化します。個人の注意力だけへ戻さず、次の差分で同じ会話を減らす仕組みにつなげます。
- Google Engineering Practices: How to write code review comments
- Google Engineering Practices: What to look for in a code review
