はじめに

これまで私は、レビューを行う際には手元でアプリの簡単な動作確認を行い、挙動に問題がなければ承認を実施していました。

本来であればコードそのものも確認したいところですが、最近は業務が忙しく、レビューに十分な時間を確保できないこともあり、まずは動作確認を中心としたレビューになっていました。

そのため、「動作上は問題なさそうだけど、このコードを本当に承認してよいのか？」という観点で、コードそのものの品質や保守性まで踏み込んでレビューすることが十分にできていませんでした。

そんな状況において、佐藤晶彦さんの『コードレビューの教科書』を読み、コードレビューで何を見るべきなのか、どのように指摘すればよいのか、改めて考えるきっかけになりました。

その中で今回は「明日からでも自分自身で取り入れたいな」と感じた、「コードレビュー時におけるコメントの書き方」について簡単にまとめてみます。

1. これまでのレビュー指摘

これまでは、レビューコメントにおいて「ここ、少し気になります」といった、対応してほしいのか、単なる意見なのかが分かりにくい表現を使ってしまうことがありました。

レビューコメントでは、

① 対応が必要か
② どの観点での指摘なのか
③ なぜ修正が必要なのか

を明確にすることが重要だと考えています。

これまでも③の「なぜ修正が必要なのか」は意識して伝えるようにしていました。一方で、①の「対応が必要か」と②の「どの観点での指摘なのか」は、コメントだけでは分かりにくいことがありました。

そこで本書を参考に、今後は「対応要否」と「修正観点」を明示し、これまで意識してきた「修正理由」と合わせて伝えたいと思います。

2. 「対応要否」を伝える（プレフィックスの活用）

コメントの頭にプレフィックス（接頭辞）をつけることで、レビュイーが「このコメントに対応が必要なのか、どの程度の対応を求めているのか」を判断できるようにしていきます。

本書で紹介されている考え方を参考に、私は以下のようなプレフィックスを使ってみようと思います。

使ってみたいプレフィックス例

[Must] ：必ず修正してほしい、バグや仕様制約違反
[Should] ：できれば修正してほしいレベル、品質や可読性向上のための推奨される記載方法
[IMO] ：In My Opinion（私としての意見）。修正するかは実装者の任意とする
[NITS] ：Nitpick（重箱の隅）。細かい書式やリファクタリング
[Q] ：質問。実装者への実装意図の確認

3. 「修正観点」を伝える

ただ「直してください」と伝えるだけでなく、「なぜ直してほしいのか」、「どの観点での指摘なのか」を明記します。
今回は、レビューコメントを書く際に特に意識したい観点として、以下の5つを挙げます。

伝えるべき主な観点

設計：実装に対して責務が大きすぎないか、拡張性はあるか
理解容易性：コードの可読性、処理の複雑性、保守性について
命名：変数・関数名の妥当性およびスペルミスについて
コードスタイル：インデントやフォーマットなどの記述形式の正当性について
ドキュメント：コメントなどの関連ドキュメントの妥当性について

観点を明記することで、単なる好みの押し付けではなく、レビュー観点に基づいた指摘であることがレビュイーに伝わりやすくなります。

4. これらを組み合わせた改善例

「対応要否」と「修正観点」を組み合わせると、これまでより指摘の意図を伝えやすくなると感じました。

❌ 従来の書き方（曖昧な指摘）

この関数、ちょっと長くて何やってるか分かりづらいかもです。

✅ これからの書き方（対応要否＋修正観点）

[Should] 理解容易性（可読性）
この関数では「ユーザー情報の取得」「権限チェック」「レスポンス生成」の3つの処理を行っています。
1つの関数で複数の責務を担っているため、処理ごとに分割すると、それぞれの責務が明確になり、コードを追いやすくなると思います。
可能であれば、処理ごとにプライベートメソッドへ切り出すことを検討してください。

5. おわりに

今回、『コードレビューの教科書』を読んでまず優先的に取り入れてみたいと思ったのが、

「対応要否」と「修正観点」を明確にしたレビューコメント

です。

レビューコメントにちょっとしたルールを設けるだけでも、

「これは直すべき？」
「これは単なる意見？」
「何が問題なの？」

といったレビュー中の認識齟齬を減らせるのではないかと思いました。

まずは自分自身のレビューからこのスタイルを取り入れ、実際に使ってみたいと思います。
そのうえで効果を感じられたら、チーム全体に対しても提案してみたいです。

なお、佐藤晶彦さんの『コードレビューの教科書』では、今回紹介したレビューコメントの書き方だけでなく、

レビュアー・レビュイーの心構え
コードレビューで見るべき観点
チームとしてコードレビューを行う際の考え方
AIを活用したコードレビュー

などについても紹介されています。
コードレビューについて体系的に学んでみたい方や、気になった方は是非手に取ってみてください！

参考

コードレビューの教科書 ―⁠ なんとなく承認から抜け出すための観点と判断基準（技術評論社）