投稿日
最終更新
カテゴリー
タグ
良いプルリクとは
まず、「なぜプルリク」を作成しているのかについて整理する。
下記のような目的が考えられる。
- コードの変更と課題をまとめる
- 成果物をレビューしてもらう
とはレビューしやすいプルリクである。
レビューしやすいプルリクにすることでレビューの時間を削減したことで開発速度の向上や、成果物の品質の向上につながる。
タイトルをわかりやすくする
プルリクのタイトルは一目で概要を把握できるように分かりやすい方がよい。タイトルは、プルリク一覧でも一番最初に読まれるものなので、プルリクの説明を読まなくても、タイトルだけで内容を把握できるようになっているのがベスト。
小さくする
プルリクの変更量が少なければ、レビュアーのへの負担が小さくなる。変更が小さければ、影響範囲も限定的になり、変更行を1行ずつしっかり確認でき不具合の見逃しをおさえることができる。変更行数が400行以下だとレビューの品質が高くなるという話もあるらしい。個人の感覚としては、100~200行程度に小さくなっているとレビューしやすい。
他にも、小さくプルリクを頻繁にマージし、ブランチの寿命を短くすることで、コンフリクトを避ける目的もある。
- 変更が多いプルリクは、事前に身構えたり、ある程度の時間をとるために後回しにしてしまうこともあり、レビューの速度も遅くなる。
変更意図を一つにする
- ついでのリファクタリングなどは極力抑える。
- ロールバックの対応もしやすくなる
- 後から見た際に、理解しやすくなる
- レビューをもらいやすい細かいプルリクの切り分け方 - Software engineering from east direction
プルリクのドキュメントを書く
- レビューしてほしいポイント
- レビューに役立つ情報
- 不安に思っていること
- APIのドキュメント
- 疑問に思うだろう箇所のコメント
- 後から見た際にもわかりやすくなる
- このプルリクでしないこと
- なぜ変更しているか分からない
- 何を変更しているか分からない
- 差分が巨大
- 複数の目的が混ざっている(バグ修正、リファクタリング、コードフォーマットなど)
- 確認手順が不明
コミットメッセージを分かりやすくする
参考文献
- 「巨大プルリク1件vs細かいプルリク100件」問題を考える(翻訳)
- レビューしてもらいやすいPRの書き方 - hydrakecat’s blog
- レビューをもらいやすい細かいプルリクの切り分け方 - Software engineering from east direction
- なぜあなたのPull Requestは読まれないのか - Qiita
- 「読めるコード」を書くための7つのチェックポイント - Qiita
- https://fujiharuka.github.io/google-eng-practices-ja/ja/review/developer/cl-descriptions.html
細かい目線
- バックエンドの場合、繰り返し処理に注意する