なぜ書くか

見やすくて理解しやすいプルリクの方が読む方も早く読めるし、出した方も早く返ってくるからなんか win-win な気がするから。

プルリクとは？

プルリクエストの略。
コードの変更をレビュワーに通知し、マージを依頼する機能。
プルリクをあげてレビューを受けることで、一人では気づけない指摘やバグや記述ミスの発見をすることができ、コードの品質を高める。

綺麗なプルリクとは？

コードを書いていない他の人が見て、すぐに概要を把握できるプルリクをここでは「綺麗なプルリク」とすることとする。

綺麗なプルリクのメリットは？

開発速度の向上
確認漏れの減少
仕様ズレの早期発見

意識すること

プルリクで何をしているかをわかる説明文を書く
プルリクの粒度を小さくする
コミットを綺麗にする
自分の意図をコメントしておく

1. プルリクで何をしているかをわかる説明文を書く

そのプルリクは何のためのもので、何をしているのかを説明文として書こう。

概要
目的
変更内容

上記の内容を書くことで、レビュアーは「このためのプルリクか」「こういうことをしようとしたコードなのか」とコードを読むための準備ができる。
準備ができるとレビュアーとしてもより早くコードの理解をすることができ、「こっちのやり方のほうがいいよ」「ここはバグ生みそう」などより質の高いFBをすることが可能になる。

さらに、UIが変更になった場合は、その before と after のスクショも一緒に貼ってあげるとお互いの認識のズレが生じにくくなり、仮にズレがあったとしてもより早い段階で気づくことができる。（下記の書き方で書ける）

before | after
---- | ----
<img src="" width="320"/> | <img src="" width="320"/>

また、もしも意図的に変更していない箇所があればそれも追記しておくと余分なコミュニケーションコストがかからない。

結論、「何をするためのプルリクか」「何をしたプルリクか」「何を変更したプルリクか」を明確にすると良い。

## 該当エピック
epic: #1111
## 概要
一文で何を実装したのかを書く。
## 目的
一文で何のために実装したものなのかを書く。
## 変更内容
- 変更内容1の修正
- 変更内容2の追加
- 変更内容3の削除
## PR除外箇所
- 除外した内容
    - 理由

2. プルリクの粒度を小さくする

変更箇所が少なければ少ないほど、レビュアーに与えるストレスは少なくなる。
変更箇所が多いと、どうしても心理的に避けてしまい、後で時間があるときに確認しようとなってしまうため待ち時間が生じる可能性が高い。
しかし、変更箇所が少ないと「これくらいだったら今確認してあげよう」となり、待ち時間が少なくFBをもらえるかもしれない。

もしも、プルリクにファイルが多くなりすぎている場合は、設計の段階でイシューを分割するべきかもしれない。
大体、一つのプルリクに多くて10ファイルがストレスを感じにくい量なのかもしれない。

結論、1プルリクに含めるファイルは最小限にしよう。多い場合は、分割できないかを考えてみよう。

※これは筆者が実際に出したプルリクである。精神的にレビュアーにダメージを与えたに違いないと反省しております。

3. コミットを綺麗にする

コミットは、機能ごとでまとめて、変更内容が何か、メッセージを読めばわかるコミットメッセージを書こう。

一般的にコミットで大事と言われていること

可読性
- commit message の読みやすさ
- 変更概要を簡単に把握できるようにする
原子性
- commit 粒度の小ささ
- 変更の粒度を不必要にあげない
論理性
- 変更が意味的にまとまっているか
- 変更は意味的にまとめて commit する

要するに、読みやすく、規模を小さく、関連している変更をまとめていると読みやすいプルリクになるということである。

可読性をあげる方法として、[Mod] [Add] [Del] [Fix] などをコミットメッセージの前につけてあげるとその内容が修正なのか、新規追加なのか、削除なのか、バグ修正なのかがコードを見なくても予想をつけることができる。
さらに、コミットメッセージには

具体性
人間的意味

の二つを持たせることを意識する必要がある。

具体性とは、例えば Fix bugs ではなく ユーザー登録フォームのボタンが押せない問題を修正 になり、
人間的意味とは、OLD_CONST1, OLD_CONST2を削除 ではなく、 ver2.0で廃止した登録関連の古い定数を削除 になる。

ex)
- [Fix] ユーザー登録フォームのボタンが押せない問題を修正
- [Add] ユーザー管理画面で複数ユーザーに対して一括で権限付与できる機能を追加

結論、関連性のある処理でまとめて、コミットメッセージだけでレビュアーが何の処理が書かれているかを把握できるようにしよう。

4. 自分の意図をコメントしておく

あらかじめの補足情報や相談をコメントにしておくことでレビュアーのプルリクに対する理解も進み、より深い議論をすることができる。
コメントは、レビュアーのためだけの機能ではなく、レビューしてもらう側も意見を伝えることができるための機能であることを覚えておこう。

結論、不安な箇所や意図がある箇所はコメントを書こう。

番外編

プルリクやコミットをする際に役に立つgitコマンド

git add --patch
- 関連のある変更をまとめることができる
git rebase -i
- コミットし忘れた内容を前のコミットとまとめることができる
- squashを選ぶことで前の内容と結合することができる
git push --delete origin some-branch
- pushしてしまったが、まだプルリクあげたくなかった時にプルリクを削除することができる
- プルリクを作成したが、出したくなくて消したい場合にプルリクをcloseにすることができる

参考サイト

https://katsuki.hatenablog.com/entry/2018/07/20/081849
https://dev.classmethod.jp/study_meeting/git-workshop-20180327/
https://ics.media/entry/14449
https://techlife.cookpad.com/entry/2016/08/17/111500

綺麗なプルリクをあげたいあなたへ