自分が実際に実務で実践出来ているかどうかは置いておいて今までの経験や技術書を読んでプルリクエストを作る上で大事だと思うことをまとめてみます。
レビューアーの立場（気持ち）で考える
これから説明することの全ての原点はこれに帰着すると思う。
コードレビューはそれなりに工数がかかる作業のためレビューアーの負担が少なくなるように前提知識や拝見等を漏れなく列挙するのが大事である。
- プロジェクト全体でかけるコストが少なくなるように意識する
- レビューアーが差分をみたらすぐにレビューできる状態にしておく
- レビューアーのコスタが低くなるようにレビューを依頼する
レビューアー向けの説明を書く
- 適切なタイトルをつけ、本文に目的、背景を書く
- 実装の根拠を書く
- 仕様や設計をまとめる（リンクや画像があれば
- コードを改善する（リファクタリング）
- 差分の説明をする
- 成果物のリンク、画像、動画等を貼る
何を実装したのか？について重点的に書く人は多い印象を受けるが意外と「なぜ」そのように実装したのか？を書く人は少ない印象を受ける。
極論、何をやっているのかはコードを見れば理解出来るし、もしコードを見て理解出来ない状態であればコードの書き方をもう一度見直す必要がある。しかし、なぜ？そのような実装になっているのかは実装者にしか分からないことが多いのでプルリクの説明だけでなく、ドキュメントコメントとして恒久的に残すのも重要である。
不要な差分は持たせず、必要十分なPRを作ることを意識する
余計な差分があると無駄に脳のメモリを消費してしまうのでプルリクを出すときは無駄な差分が無いかどうかチェックしましょう。
色々蛇足で修正し続けたりしてプルリクの粒度が大きくなりすぎたらプルリクを分けるなどするのが重要です。
- プルリクの目的を一つに絞る。
- プルリクの粒度は小さく保つ。一つの機能でもプルリクの粒度が大きくなりそうであれば分割を検討する。
最後に
レビューアーをやったことない人はどこか早いタイミングでレビューアーを経験すると良いでしょう。
他人のコードをレビューしてみてはじめてレビューアーの気持ちが分かり思いやりのあるプルリクが作れるようになるのではないでしょうか。