「伝わるコードレビュー」という本を読みました。この本はコードレビューでのコミュニケーション（特にテキストコミュニケーション）を円滑に行う要点を書いた本です。レビュアーとしてもレビュイーとしてもコードレビューを行う機会が増えてきたので読んでわかったことをまとめることにしました。
本の内容としては大きく「コードレビュー時の心構え」、「シーン別の実践方法」、「TIPS」の章に分かれ、それぞれの章でレビュアー・レビュイー双方のすべきことが書かれています。
コードレビューで起こりがちな問題
レビュアー側
レビュアー側は意図せず次のような振る舞いをしてしまう場合があります。
- 攻撃的・独善的な指摘
- 本人はそうと意識していない場合も含む
- それを避けようとして回りくどい表現を使う
- コードを書いた背景を確認せず修正を指示する
レビュイー側
特に、まだ経験の短いレビュイーはレビューに対して警戒心を持ちやすい傾向があります。
その結果、以下のような行動につながることがあります。
- レビューコメントの裏にある意図を過剰に推測する
- 「本音と建前」のようなものがあると思ってしまう。たとえば、「直接的に直してほしいとは書いていないが、直した方がいいのでは？」と受け取ってしまうなど
- 情報を出し惜しみする
- 何か突っ込まれたときの防御壁になるように隠してしまう
- 必要以上に防御的になる
- 修正指摘を考えなしに受け入れる
なぜこのような問題が起こるのか
これらの問題はレビュアー・レビュイーの双方がコードではなく「人」を評価対象として認識してしまうことで発生します。
たとえば双方
- 自分の能力が低いと思われたくない
- 相手は手を抜いているのではないか
といった意識が強くなると、レビューの評価対象が人に移り、正しいレビューができなくなります。
コードレビューの目的は人を評価することではなくコードの品質向上と問題解決にあるので、以下を意識する必要があります。
- お互いの前提知識を揃える
- 率直さと明瞭さを重視する
- チームとして仕組みを整備する
「お互いの前提知識を揃える」について
認識のずれはレビュー効率を大きく下げます。
レビュアー・レビュイー双方が以下を意識すると、認識のずれを減らしやすくなります。
- 相手の意図（コードを書いた意図、指摘の意図）を断定しない
- 自分の考えや判断理由を添える
- 「バグ修正」などの抽象的なコメントを避けて詳細に書く
- 必要な背景情報を明示する
- 相手が見落としている可能性がある点は念のため確認する
- 一度に多くの論点を投げない、質問・指摘は段階的に行う
- 複数の質問・指摘・仮説などを一度に投げると読んだ人の思考の負荷が高まる（後述）
「一度に多くの論点を投げない、質問・指摘は段階的に行う」について
たとえば以下のような質問の記述方法は避けるべきとされています。
3点質問があります。
1. これは A と B のどちらですか？
2. A だとすると〜
3. B だとすると〜
4. また、○○はxxの認識で良いですか？
上記の記述方法について良い点として
- 最初に質問の数を明記している点
- 「どちらですか？」というクローズドクエスチョンを用いている点
- 箇条書きで書いている点
があります。しかし悪い点として
- 「だとすると～」で質問が分岐している点
- 一度のコメントで「また、～」という異なる種類の質問を一緒にしている点
が挙げられます。これらの点は回答のとりこぼしを招くため良くないとされます。
この場合は以下のように相手の回答によって次のアクションが変化する質問や異なる種類の質問を分離することでやり取りが簡潔になりやすく、認識のずれ、回答の取りこぼしも発生しにくくなります。
- まずは「これは A と B のどちらですか？」を確認し、その回答を受けて再度AまたはBについて質問する
これは A と B のどちらですか？
- 「また、○○はxxの認識で良いですか？」は、別のコメントに分離して投稿する
～～（新規コメントの作成）～～
○○はxxの認識で良いですか？
「お互いの前提知識を揃える」ときにレビュアーが意識すること
- 修正を指示する前に実装意図・背景情報を確認する
- 「なぜこの実装になったのか」を理解してから指摘する
「お互いの前提知識を揃える」ときにレビュイーが意識すること
- 修正指摘を無条件に受け入れない
- たとえば、指摘に背景情報と矛盾する点があったとき「あの人が言っているからそうなのだろう」、「レビュアーも背景情報はわかっているだろう」などと考えて考えなしに指摘を受け入れ修正しない
- 判断理由や実装意図を説明する
- 「やったこと」だけでなく、「やっていない」ことも共有する
- スコープの明確化
「率直さと明瞭さを重視する」について
曖昧なコミュニケーションはレビューコストを増加させます。
以下を実践するとやり取りの効率は大きく改善します。
- 詰まっていることを率直に伝える
- 「何が分からないのか分からない」状態でも共有する
- 相手に何をしてほしいのか明確に伝える
- すぐに回答できない場合は、その旨を伝える
- Yes / No や特定の選択肢から回答できる質問を心掛ける（クローズドクエスチョン）
- 箇条書きを使って論点を整理する
- コメントテンプレートを用意する
- コメントテンプレートは記載漏れの防止や、必要な情報がどこにあるかをレビュアーが素早く把握できるという利点がある
「チームで仕組みを作る」について
個人の努力だけでは限界があるため、チームとしてルールや仕組みを整備することも重要です。
例えば以下のような取り組みがあります。
- コメント用のタグやラベルを定義する
- たとえば、質問コメントには先頭に
[ask]と書くなど
- たとえば、質問コメントには先頭に
- 作業ログを残す
- 作業ログには事実だけでなく自分の考えも記録してよい
- なぜその方法を選んだのか
- ほかにどんな選択肢があったか
- 理由や根拠
- 作業ログには事実だけでなく自分の考えも記録してよい
- 参照先のリンクを共有する
- 一定時間悩んだら相談するルールを設ける
- チャットが長引いたら通話に切り替える
- 質問先を明示し、必要に応じてメンションする
まとめ
コードレビューでは、コードそのものよりもコミュニケーションがボトルネックになることが少なくないと思います。
レビュアー・レビュイーの双方が、評価対象を人ではなくコードだと認識したうえで
- 相手の意図を決めつけない
- 明確で率直なコミュニケーションを行う
- チームとして仕組み化する
ことを意識することで、レビューの目的であるコード品質の向上と問題解決に集中しやすくなります。