思わずレビューしたくなるプルリクエストを考えよう

アプリケーション開発を円滑を進行するにあたってGitはなくてはならない存在です。GitHubをはじめとするプラットフォームサービスでは開発をサポートする様々な機能が提供されていますが、中でも必須級のものがみなさんも良くご存知のプルリクエストで、開発ワークフローの肝であると言って良いでしょう。（GitLabではマージリクエストと呼ばれます）

この記事では、どのようなプルリクエストが効果的にワークするのか、「良いプルリクエスト」について考えていきたいと思います。「プルリクエストとは何か？」といった説明についてはここでは触れません。

プルリクエストは何のため

まず前提として、プルリクエストの目的について考えてみましょう。

1. レビューによりコードの品質を向上・担保するため
2. 変更の履歴を記録しておくため
3. 変更内容をチーム内で情報共有するため

プルリクエストは記録であり、コミュニケーションツールであり、アプリケーションの品質を高めるための手段です。この目的を踏まえ、プルリクエストは誰に向けて作るものなのか考えてみましょう。

1. レビュワーのため
2. 未来の担当者（あるいは未来の自分）のため
3. チームメンバー・クライアントのため

つまり、チームメンバーに変更内容が正確に伝えられること、そしてレビュワーがレビューしやすいように情報が適切に整理されていることが「良いプルリクエスト」の条件であると考えます。

良いプルリクエストを考える

では、「良いプルリクエスト」に必要な要素を具体的に考えていきます。

適切なサイズであること

「レビューのしやすさ」を考慮した時、プルリクエストのサイズは最も気を配らなければいけないポイントです。差分が大きすぎたりタスクと無関係なコミットが混ざっていたりすると、レビューが困難になりレビュワーに大きな負担をかけることになります。

• 不要なコミットを含まないこと
• 不要なファイル差分を含まないこと
• 作業範囲・作業粒度が適切であること

タスクと直接関係のないコミットや差分はプルリクエストから削るよう努め、レビュワーがスコープ内のレビューに集中できるようにします。また、不要な差分を省いてもなお変更量が膨大である場合、そもそもの作業範囲が適切でなかった可能性があります。適切な粒度への分割を検討しましょう。

ディスクリプションを整備する

プルリクエストのディスクリプションにはレビューに必要な情報を明記するようにしましょう。

作業者が想像する以上にレビューはコストがかかるものです。特に着手時にかかるスイッチングコストは非常に高くなりがちなので、レビュワーがすぐに内容を確認出来るような情報をしっかりと整備するように心がけます。

例えばこのような情報を揃えておきたいです。

他にもレビューするうえで役立ちそうな情報があればなんでも記載しましょう。タスクの背景や仕様策定の経緯など、「なぜ」の情報があると精度の高いレビューの助けになるはずです。

ディスクリプションを整備するうえで、作業者自身の作業コストが気になるかもしれません。できるだけ低いコストで重要な情報をまとめられるように、テンプレートなどを用意しておくと良いでしょう。また、タスクの情報についてはレビュワーよりも作業者の方がより高い解像度で把握しているはずなので、作業者が整備する方が効率的です。

コメントをつけておく

共有しておきたい補足情報があったらコメントをつけておくとよいです。コードに直接コメントを記載しておけばレビュー時はもちろん、あとからコードを見返す際に参考にする事ができますし、GitHub等ではプルリクエスト上でコードの指定位置にコメントをつけることもできます。

見て欲しいポイントやそのコードを書いた経緯などの情報をそのコードの近くに付記しておくことで、レビュワーは欲しいタイミングで補足情報を知ることができるため、非常に助かります。ディスクリプションを見に戻る必要もなく、阻害されることなくレビューを進めることができるでしょう。

最後に

この記事に書いたような事はすでに実践している当たり前のことと思われたかもしれませんが、こういったノウハウはメンバーみんなで意識することでその効果を十二分に発揮できるものです。

Gaji-Labo ではチームを強くするためにさまざまな知見をチーム標準として整理するプロセスを進めています。チームが強くなれば、さらに高い価値を届けることができるようになるでしょう。