プルリクエストを出す際に意識してほしいこと

最近コードレビューをする機会が多いのですが、プルリクエストの中でもレビューしやすいものとそうでないものがある事を実感しています。

というわけで、レビュアーとしての観点からどんなプルリクエストだと助かるのかについてまとめてみました。上から重要だと思う順に書いています。

1. 何を実現したいのかを書く

そのプルリクエストで何を実現したいのかのインプット情報が多いほどレビューしやすくなります。例えば以下のような項目です。

概要、目的、要件、設計、テストケースetc...

また、併せてどのような観点でのフィードバックを求めているかも伝えられると親切です。

レビュアーに対してだけでなく、あとからチームに加わったメンバーが読んだときにも理解しやすくなります。

リポジトリ直下に PULL_REQUEST_TEMPLATE.md という名前のファイルを配置することでプルリクエストをつくるときのフォーマットを設定できるので、運用の際はそれを活用するといいと思います。

2. プルリクエストの粒度はなるべく小さくする

変更の差分が数十ファイル以上もあるようなプルリクエストはレビュアーの精神をとてもすり減らします。

逆に粒度が小さいほどレビューする方も気持ち的に楽なのですばやく取り組むことができます。

感覚的には10ファイル以内に収めてもらえると助かります。

なぜプルリクエストが巨大になるのか？

設計が完了する前にコードを書き始めることがだいたいの原因かなと思っています。どこで分割していいかわからないまま結局一つのプルリクエストにすべてが収まってしまうのではないかと。

設計が完了してイシューが分割できていればプルリクエストも細かくできるはず。いやほんと、差分ファイルが多すぎるのは見るだけで疲弊します（切実）。

3. 自らコメントをつけておく

実装者がプルリクエストのレビュー依頼を出す前にあらかじめ補足事項や相談をコメントしておきます。例えば以下のようなコメントです。

• 「ここは◯◯の意図でこのような実装になっています。」
• 「ここはこうしたけど◯◯の点で問題はないでしょうか。」

このようなコメントはレビュアーの理解を助け、設計における建設的な議論にもつながるため積極的に行うべきだと考えます。

4. 綺麗なコミットログをつくる

プルリクエストの粒度を小さくしたほうがいいと書きましたが、やむを得ず差分の量が多くなってしまう場合もあると思います。

そういったときにコミットログが綺麗だとストーリーに沿って順を追ってレビューできるためとてもやりやすいです。逆に複数の変更内容を1コミットにまとめられるととてもレビューしづらいです。

コミットメッセージの内容

コミットログに書くコミットメッセージは以下のような感じでサブジェクトに「変更内容（What）」を、メッセージに「変更理由（Why）」書きましょう。変更理由があることで、ソースコードから書き手の意図を頑張って読み取るコストが省けます。

1行目：変更内容の要約（タイトル、概要）
2行目 ：空行
3行目以降：変更した理由（内容、詳細）

参考: Gitのコミットメッセージの書き方

まあこれら関しては正直毎回いちいち綺麗にするの大変なので、大量の差分が出たときだけはせめてやってほしいという感じです。

Status checkはクリアしとこう。

あれ、大丈夫？ってなるので。

クリアしてなくてもいいけど、その場合は理由を書いておいてもらえると助かります。

View変更のスクショを貼る

Viewを変更している場合はBefore, Afterのスクショを貼ってもらえると動作確認する手間が省けて助かります。

まとめ

少しの工夫を加えるだけで何倍もレビューしやすさが変わるので、ぜひ参考にしていただけると幸いです！