コードレビュー時に意識しているコミュニケーションやプロセス

こんにちは。アルダグラムでエンジニアしている前山です。

日々の開発フローの中で、コードレビューは品質と知見共有の両面で欠かせないステップです。それは単なるチェック作業ではなく、より良いプロダクトを生み出すための重要なコミュニケーションの場でもあると思います。

開発に関するチームの振り返りでも、たまにコードレビューに関して話題に上がるので、今までトピックに上がった内容や自分が意識しているコミュニケーションやプロセスについて、レビュアーとレビュイー両方の視点からお話しできればと思います。

レビュアー視点

まずはレビュアー視点で意識していることを紹介します。

ポジティブなコメントを心がける

レビューで目が行きがちなのは改善点ですが、同時に良いコードや工夫が感じられる部分を褒めたり、対応に関して感謝することも大切です。「この書き方は分かりやすいな」「この処理は勉強になる」と感じた部分があれば、素直に言葉にしたり、絵文字等のリアクションをつけるように心がけています。

レビューコメントに温度感がわかる prefix をつける

コメントの内容が細かな修正依頼なのか、設計全体を見直す必要があるのか、コメントの「重み・温度感」を明示的に示すことで、レビュイーは対応の優先度を判断しやすくなります。

たとえば以下のような prefix を用います。

prefix	意味
must	必ず確認・修正してほしい
imo	個人的には修正した方がいいかなと考えている
nits	些細な指摘。重箱の隅をつつく提案
q	質問。何故そのようなアプローチが取ったのかなど、意図を知りたいとき

コメント一つ一つに温度感がわかる prefix をつけることで、レビューコメントがすべて同列にならず、重要度の低い提案が明確になるので、レビュイーの負担を軽減することができます。また、こういった prefix をつけることで、締め切りに追われる状況 (プルリクエストをマージするために must で対応しないといけないかどうか) において柔軟性も提供できます。

細かいコメント (nits) だけなら、先に approve する

上記の「レビューコメントに温度感がわかる prefix をつける」に続いた話ですが、nits など、細かい指摘コメントはマージブロックになることはないので、先に approve を出して、「この部分は直せたら直しておいてね」程度の温度感で伝えると、レビュイーは余裕を持って後から対応できます。これにより、コミュニケーションの往復が減り、スムーズなデリバリーを実現しやすくなります。

また、同じような nits が頻出する場合、それはリンターやフォーマッターなどの自動化ツールで解決できる可能性を示唆しています。細かい指摘は人からよりもツールからの方が受け入れやすく、チーム内の摩擦を減らす効果も見込めるので、こういう場合は自動化を検討するといいでしょう。

多くのコメントが必要になりそうなときは、非同期ではなく同期的コミュニケーションに切り替える

プルリクエスト上で多くのコメントが発生しそうな場合は、テキストベースの非同期コミュニケーションに固執せず、ミーティングや通話といった「同期的」なコミュニケーションに移行することを検討します。

非同期でのコメントのフィードバックが多くなると、たとえ言葉が丁寧であっても、受け手にとって「責められている」という感情を呼び起こす可能性があります。そういう場合は、オープンなコミュニケーションよりも、クローズドな環境で直接話すほうが、誤解を減らし、建設的な結論に至りやすくなります。

こうした「プライベートな同期コミュニケーション」は、批判としてではなく「一緒により良い方向へ導く対話」として受け止められやすく、結果として当事者同士の信頼関係構築にもつながり、やり取りがスムーズになりやすいです。要は、多くの修正を要する場面では、テキストコメントだけで完結せず、状況に応じて対話形式に切り替える柔軟性を持つことが大切だと考えています。

レビュイー視点

次にレビュイー視点で意識していることを紹介します。

プルリクエストは小さめに

大きすぎるプルリクエストは、レビュアーに大きな負荷を強いるだけでなく、バグや仕様変更点を見落とすリスクを増大させます。可能な限り、機能単位やロジック単位などプルリクエストを分割し、一度にレビューする範囲を明確に絞り込むことで、レビュアーは全体像と細部を把握しやすくなります。

プルリクエストが大きくなったり、チームがあまり知見を持たないドメインに触れるときはレビュー前に同期的な説明を

開発の進め方やタスク内容によっては、どうしてもプルリクエストが大きくなったり、チームがあまり馴染みのない技術やドメインに触れるケースも出てきます。
そうした状況では、レビューを依頼する前に、実装方針やコードの背景を同期的なミーティングで事前共有することが有効です。

「この実装で何をしているのか」「どんな考えのもとでこのアプローチに至ったのか」といったポイントを、レビューに臨む前に口頭で説明しておけば、レビュアーはコードを読む際の手がかりを掴みやすくなります。結果として、レビューは単なる問題指摘の場ではなく、チーム全員が理解を深め、より良い解決策を模索するコミュニケーションの場へとシフトします。

また、実装前に Design Doc などを用いて設計方針や意図をドキュメント化しておくと、同期的な説明とあわせて理解がよりスムーズに進むかなと思います。

プルリクエストには背景や理由をしっかり残す

レビュアーとレビュイーの間には、どうしても情報量に差が生じます。レビュイーは実装に至るまでに多くの検討や試行錯誤を重ねている一方、レビュアーは完成した差分を初見で眺める立場です。そのため、「なぜこの実装にしたのか」「他の方法は検討したのか」といった背景や判断理由をプルリクエストの説明文やコードコメントとしてわかりやすく示しておくことが重要になります。

こうした情報が不足していると、たとえ正しい判断や工夫があっても、レビュアーは「どうしてこのやり方なのか？」と迷い、必要以上に時間や労力を割くことになります。一方、詳細な背景説明があれば、レビュアーはコードをよりスムーズに理解し、的確なフィードバックを返せます。

また、セルフレビューの段階で「あえてこのアプローチにした理由」や「この処理は将来的な拡張性を考慮したもの」など、特に見てほしいポイントをコメントで残しておくと、レビュアーは的を射たコメントや改善案を提示しやすくなります。

最後に: 参考にしている記事や書籍

最後に、個人的に参考にしている記事や書籍をいくつか簡単にご紹介します。

Kind Engineering
積極的に親切な同僚になる方法について、具体的なアドバイスがまとめられています。「スタッフエンジニアの道」という書籍で紹介されていました。相手の立場に立って考え、率直で丁寧なフィードバックを通じて心理的安全性を高めるなど、チーム内のコミュニケーション改善に役立つヒントが書かれています。

https://kind.engineering/

コードレビューはつまらないから丁寧なプルリクエストでチームの生産性向上を目指す
レビュアーとレビュイー間の情報量のギャップに着目し、丁寧なプルリクエストを作成することによって効率的なレビューサイクルを生み出す考え方が紹介されています。

https://blog.tai2.net/how-to-code-review.html

Googleのソフトウェアエンジニアリング
かなりのボリュームがある本で、社内で輪読会を開催して、じっくり読み進めました。第9章はコードレビューを取り上げており、コードレビューにおける「開発者の尊重」や「質問」の大切さなど、非常に参考になるコードレビューの指針が書かれています。

https://www.oreilly.co.jp/books/9784873119656/

同僚や先輩エンジニアから学ぶ
これは記事や書籍ではありませんが、日常業務の中で「いいな」と思ったコードやコードレビュー、進め方があれば積極的に真似することが重要です。本記事で紹介した内容のほとんどが、実際には同僚や今まで出会った先輩エンジニアから学んだものです。

今後も学ぶ姿勢を大切にし、新しい知識や手法を素直に取り入れながら、より良いコードレビューを実践していければと思います。