対象

最近PR(プルリクエスト)を使用しているチームにジョインした新人。
特に「PRは初めて」とか「PRが苦手」という人向け。

初めに

先月チームにジョインした新人です。
チーム開発が初めてということもあってか、最近PRを送ること自体が楽しいです。

PRはコードの品質を保つのが1番の目的ではありますが、新人にとっては毎回の実装を先輩にコード単位で(強制的に)レビューしてもらえるので勉強するために凄くいい仕組みだなと思います。

とはいえ先輩も神ではないので、どんなPRでも意図を汲み取れるわけではありません。
いいフィードバックを貰うには、理解しやすいPRを出すのが大事です。

頭では分かっていても面倒に感じるとなかなか定着しないので、楽しく継続できるようにすることが大事だと思っています。

まだ試行錯誤中ですが、
理解しやすいPRにするために大事だと思ってること
それを楽しく実践するために取り組んでいること
をまとめます。

tl;dr

コミット編
- コミットを細かく切る
  - git logで自分の進捗に浸る
  - 絵文字コミットしてみる
- コミットメッセージにWhatとHowを書く
  - コミットメッセージを予言する
PR編
- 第三者にも分かるPRにする
  - PRメッセージに引用を乗せる
  - PRメッセージに検討したことを書く
  - PRメッセージに画像や表を使う
  - WIP(作業進行中)のPRを上げる
終わりに
参考資料

コミット編

コミットを細かく切る

自分のセープポイントを作るって意味でも細かくコミットしていたいですが、そもそもコミットする癖がついてないと難しいです。

どの細かさがいいのかはまだ掴めてないですが、1行書いて「これは何の変更か」を言える変更となるならコミットしていいと思っています。
行ったコミットはfixupコミットやrebaseなどで整理出来るので、細かすぎる分には後で整えれば問題ないです。
勿論後からコミットを分割するのもある程度できますがやや面倒なので、細かすぎるくらいでいいと思います。

git コミットログを綺麗にしたい。fixupとsquash - かもメモ

しかし最初はそもそもコミットがただの面倒でしかなかったです。
なので癖づけのために楽しくコミットするのが大事だと感じています。

`git log`で自分の進捗に浸る

仕事終わりに今日生やしたLogを確認すると、満足感に浸れます。
翌日の出勤時に、昨日行ったコミットを眺めるのもまた乙なものです。

私は眺める用のサブコマンド作って眺めるようにしています。

便利な「git-サブコマンド」を作成する

絵文字コミットしてみる

淡白なコミットは絵文字が入ると途端にリッチに見えて嬉しいです。
行頭にコミットのカテゴリを示す絵文字をつければ可読性と共にテンションも上がります。

GitHubのコミットメッセージに絵文字を入れて開発効率をあげる

コミットメッセージにWhatとHowを書く

5W1Hとまではいきませんが、そのコミットで「何をどのように変更した」のかは書くべきだと思います。
PRをレビューする時にはコミットメッセージから差分に飛んでレビューする事になるので、
一目でそのコミットの概要が分かることが大事です。

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

コミットメッセージを予言する

先に「これをこのように変更する」つもりでコードを書き始めれば、コミットメッセージに困りません。
ついすぐ手を動かしたくなってしまいよくわからないまま書き始め、100行越えのクソコミットが爆誕することが私はよくあります。
大抵そういうコミットは後でリファクタすることになるので、先が見えない時は1度考えてから書こうと決意しました。

PR編

第三者でも理解できるPRにする

レビューしてもらうために分かりすくするのは勿論ですが、それ以上に情報を充実させるのもいいと思います。
というのもPRは数ヶ月後の自分や、新しくジョインする未来の同僚などの第三者が変更を理解するための最高のドキュメントだからです。

「何をどのように」はコミットメッセージに書けばいいと思いますが、
「なぜこのように変更したのか」「なぜ他の方法を取らなかったのか」は意識しないと抜け落ちがちだと思います。
というのも「なぜ」の文脈は十分現在のメンバーに共有されており必須ではない場合も多いからです。
しかし書くことでより価値の高いドキュメントになると思います。

PRメッセージやコード中のコメントアウトなどに「なぜ」も残すようにします。
第三者でも分かるPRが先輩がレビューしやすいのは言うまでもありません。
また意図が分かれば代替案を先輩が提示しやすくなります。