コードレビューの言葉が伝わらない原因とレビューアーの言語調整術

レビューコメントを書いたのに「意図が伝わらない」「刺々しくなった」「反発された」 -
レビューアーなら誰しも経験するこの悩み。その多くはコード内容ではなく、言語の設計と表現に起因します。

本マニュアルでは、レビューアーが意図を正確に、かつ建設的に伝えるための言語調整スキルを解説します。
レビューコメントは、「何を言うか」だけでなく「どう言うか」でコード品質もチーム文化も大きく変わります。

言葉が伝わらない3つの典型的パターン

レビューで最もよく見られる「伝わらない」状態は、以下の3つに大別できます。

1. 意図が読み取れない（情報不足）

Comment 
@Reviewer: この書き方だと微妙です。
  • どの観点で「微妙」なのか不明
  • 何を期待しているかが読み取れない

2. 解釈が分かれる（文脈が曖昧）

Comment 
@Reviewer: ここ、違和感あります。
  • 読む人の経験・価値観によって意味が変わる
  • 「どの点に」「なぜ」違和感を持ったかが曖昧

3. トーンが攻撃的に見える（語調ミス）

Comment 
@Reviewer: さすがにこれは無いですね。
  • 内容に正当性があっても、表現が強すぎる
  • 相手の受け取り方次第で反発を招く

なぜレビューコメントは誤解されやすいのか？

人間の言語には「構造と言葉の非対称性」があり、同じ単語でも使い手によって意味がズレます。
レビューではこの差がとりわけ強く出ます。

非対称性の構造
  • 書き手（レビューアー）は「文脈・設計背景・期待」を内包してコメントを書く
  • 読み手（開発者）は「PRの差分とコメントだけ」で解釈を試みる
    この非対称性により、「伝えたつもり」と「伝わっていない」が発生します。

また、Slack等で即時反応が返ってこないレビュー環境では、その場での補足が困難であることも、誤解が拡大する要因です。

レビューアーが意識すべき3つの言語調整軸

レビューアーとしての言語設計は、以下の3軸で調整する必要があります。

1. 観点の明示：「どの軸」で見ているかを明確に

- ここ、ちょっと雑な印象です。
+ このロジックは責務が分散していて、保守性の面で懸念があります。

観点（例：保守性／可読性／再利用性／拡張性）が明示されていると、相手は「何を基準に修正すべきか」を把握できます。

2. 論理の構造化：「何を→なぜ→どうしてほしい」の順に

Comment 
@Reviewer: この変数名は内容を正確に表しておらず、将来的に拡張されたときに意味が曖昧になる懸念があります。`userStatus`など具体的な名称への変更をご検討ください。
  1. 何を（指摘対象）
  2. なぜ（理由・背景）
  3. どうしてほしいか（具体的行動）

この3ステップ構成は、読み手の混乱を防ぎ、実際の行動につながりやすい書き方です。

3. 言葉のトーン調整：「提案」の形を維持

レビューコメントは「命令」ではなく「提案」が基本です。
トーン調整のポイントは以下。

表現 推奨理由
「〜が良いかもしれません」 調整的ニュアンスで受け入れやすい
「〜のような形も検討できそうです」 選択肢を示す形で押しつけ感を減らす
「〜だと意図が伝わりやすくなると感じました」 主観表現で断定を避ける

言い換え事例集：NGからOKへのレビューコメント変換

NG表現 改善表現
これは意味がわからないです 「この処理の目的が読み取れなかったため、コメントなどで補足いただけると助かります」
変数名、ひどいです 「変数名が処理内容を十分に表現していない印象があるため、再検討をご検討ください」
なんでこう書いたんですか？ 「この実装意図をもう少し詳しくお伺いしたいです。設計背景があれば教えていただけますか？」
もっとちゃんと考えてください 「他のケースにも対応できる構造にすると、再利用性が上がると思います」
書き手主語 → 受け手主語の変換

「私はこう思う」から「あなたがこうするとより良くなる」への変換は、相手の行動を引き出す言語設計につながります。

言語調整に役立つテンプレ構文集（レビューアー用）

用途 テンプレ文
判断の前置き 「〇〇のように読み取りましたが、」
懸念の提示 「〜の可能性があるように思います」
提案の開始 「〜のような形も検討してみてはいかがでしょうか」
質問のトーン調整 「もし考慮済であればご教示ください」
指摘のクッション 「念のための確認ですが、」／「少し気になったのですが、」

コードコメント例：悪い vs 良い

差分コード 
const data = fetchData();
if (data !== null) {
  process(data);
}
悪い例 
@Reviewer: こんなの普通nullチェックしないでしょ
良い例 
@Reviewer: `fetchData()`がnullを返すケースがどのようなときか分からなかったため、意図や仕様をコメント等で補足いただけると判断しやすくなります。

誤読されやすい単語リスト（レビュー文脈における注意語）

語句 リスク 代替表現例
雑 主観が強く、攻撃的印象 「設計上の根拠が読み取れないように感じました」
やばい／無理 感情的表現に見える 「この構造では要件追加に対応できない懸念があります」
なんで？ 詰問のように感じられる 「意図をもう少し詳しく教えていただけますか？」

なぜレビューアーが「言語設計」を担うべきか？

レビューアーは単に「指摘する人」ではなく、設計意図を言語化し、次の設計判断を促すナビゲーターです。
その役割を果たすには、技術知識だけでなく伝達技術＝言語設計力が不可欠です。

UML Diagram

チームとしてレビュー言語を整えるための実践案

  • レビュー言語スタイルガイドの共有

    • 「懸念はこう表現する」「提案はこの言い回しを使う」などの共通テンプレートを用意

  • NGレビューコメント収集と言い換え練習

    • 過去のやりとりから「伝わりづらかったコメント」を例示し、改善案を議論

  • レビュアー同士のクロスレビュー

    • 他のレビュアーが書いたコメントをレビューし合うことで、言語の粒度・距離感を調整

まとめ：レビューアーに必要な「言語設計力」

  • 伝えたつもりで済ませず、どう伝わるかを常に意識する
  • 観点・理由・提案の三構造でコメントを書く
  • トーンを「指摘」から「支援」へ調整する
  • 誤解されやすい語句を避け、相手が受け取りやすい言葉を選ぶ

レビューコメントとは、設計の延長線上にある設計言語の一部です。
その言葉が、チームの設計水準と文化を作ります。