対象
最近PR(プルリクエスト)を使用しているチームにジョインした新人。
特に「PRは初めて」とか「PRが苦手」という人向け。
初めに
先月チームにジョインした新人です。
チーム開発が初めてということもあってか、最近PRを送ること自体が楽しいです。
PRはコードの品質を保つのが1番の目的ではありますが、新人にとっては毎回の実装を先輩にコード単位で(強制的に)レビューしてもらえるので勉強するために凄くいい仕組みだなと思います。
とはいえ先輩も神ではないので、どんなPRでも意図を汲み取れるわけではありません。
いいフィードバックを貰うには、理解しやすいPRを出すのが大事です。
頭では分かっていても面倒に感じるとなかなか定着しないので、楽しく継続できるようにすることが大事だと思っています。
まだ試行錯誤中ですが、
理解しやすいPRにするために大事だと思ってること
それを楽しく実践するために取り組んでいること
をまとめます。
tl;dr
- コミット編
- コミットを細かく切る
-
git logで自分の進捗に浸る - 絵文字コミットしてみる
-
- コミットメッセージにWhatとHowを書く
- コミットメッセージを予言する
- コミットを細かく切る
- PR編
- 第三者にも分かるPRにする
- PRメッセージに引用を乗せる
- PRメッセージに検討したことを書く
- PRメッセージに画像や表を使う
- WIP(作業進行中)のPRを上げる
- 第三者にも分かるPRにする
- 終わりに
- 参考資料
コミット編
コミットを細かく切る
自分のセープポイントを作るって意味でも細かくコミットしていたいですが、そもそもコミットする癖がついてないと難しいです。
どの細かさがいいのかはまだ掴めてないですが、1行書いて「これは何の変更か」を言える変更となるならコミットしていいと思っています。
行ったコミットはfixupコミットやrebaseなどで整理出来るので、細かすぎる分には後で整えれば問題ないです。
勿論後からコミットを分割するのもある程度できますがやや面倒なので、細かすぎるくらいでいいと思います。
git コミットログを綺麗にしたい。fixupとsquash - かもメモ
しかし最初はそもそもコミットがただの面倒でしかなかったです。
なので癖づけのために楽しくコミットするのが大事だと感じています。
git logで自分の進捗に浸る
仕事終わりに今日生やしたLogを確認すると、満足感に浸れます。
翌日の出勤時に、昨日行ったコミットを眺めるのもまた乙なものです。
私は眺める用のサブコマンド作って眺めるようにしています。
絵文字コミットしてみる
淡白なコミットは絵文字が入ると途端にリッチに見えて嬉しいです。
行頭にコミットのカテゴリを示す絵文字をつければ可読性と共にテンションも上がります。
GitHubのコミットメッセージに絵文字を入れて開発効率をあげる
コミットメッセージにWhatとHowを書く
5W1Hとまではいきませんが、そのコミットで「何をどのように変更した」のかは書くべきだと思います。
PRをレビューする時にはコミットメッセージから差分に飛んでレビューする事になるので、
一目でそのコミットの概要が分かることが大事です。
コミットメッセージを予言する
先に「これをこのように変更する」つもりでコードを書き始めれば、コミットメッセージに困りません。
ついすぐ手を動かしたくなってしまいよくわからないまま書き始め、100行越えのクソコミットが爆誕することが私はよくあります。
大抵そういうコミットは後でリファクタすることになるので、先が見えない時は1度考えてから書こうと決意しました。
PR編
第三者でも理解できるPRにする
レビューしてもらうために分かりすくするのは勿論ですが、それ以上に情報を充実させるのもいいと思います。
というのもPRは数ヶ月後の自分や、新しくジョインする未来の同僚などの第三者が変更を理解するための最高のドキュメントだからです。
「何をどのように」はコミットメッセージに書けばいいと思いますが、
「なぜこのように変更したのか」「なぜ他の方法を取らなかったのか」は意識しないと抜け落ちがちだと思います。
というのも「なぜ」の文脈は十分現在のメンバーに共有されており必須ではない場合も多いからです。
しかし書くことでより価値の高いドキュメントになると思います。
PRメッセージやコード中のコメントアウトなどに「なぜ」も残すようにします。
第三者でも分かるPRが先輩がレビューしやすいのは言うまでもありません。
また意図が分かれば代替案を先輩が提示しやすくなります。
PRメッセージに引用を乗せる
Issueベースだったり、前のPRの続きとして作られたPRは必ず引用元を記載します。
GitHubなら #1234 のように簡単にリンクを貼れるので、PRメッセージの頭に
ref #1234
みたいな感じで載せています。
GitHubでのリンク(issue/pull request/wiki etc)
PRメッセージに検討したことを書く
機能を実装する上で選ばなかった方法があれば記載します。議論や検討が多いほどその実装に至った理由を、特に第三者が理解しやすくなります。
また次のPRで実装予定の機能があればそれを書いておくのも、確認の手戻りが少なく済みます。
GitHub「完璧なプルリクの書き方を教えるぜ」 - Amitica
PRメッセージに画像や表を使う
複雑な実装になるほど文章だけだと伝わり辛いです。
逆に言えば画像や表に頼れば説明が楽になります。
DBマイグレーションであればカラムを単語の羅列にするより表の方が見やすいと思いますし、フロントエンドならスクショがあれば説明はほとんど不要です。
遷移やリアクションがあるようなフロントの実装ならGIFを貼るのもいいかもしれません。
WIP(作業進行中)のPRを上げる
終了してない段階でPRを上げるのはいい習慣だと思います。
成果物を出さなきゃ！と思うとPR作成の心理的ハードルが上がりますが、作業途中の相談の場として使えば簡単にPRを出せます。
選択した方法が悪ければ途中で修正できるので、手戻りも少なく済みます。
困っている事があればPR上で議論でき、その議論は残るので3.で書いたようないいドキュメントになります。
いわゆる報連相が全部出来るので、うまくいかない時ほどおすすめです。
終わりに
皆さんの理解しやすいと思うPRをコメントで教えて下さい！
もしよさそうだったらGoodボタンよりもLGTM画像でコメントしてくれると喜びます！
