最近、本格的にチーム開発が始まってきたので、これを機にPull Requestを書くときに何を意識しているのかをまとめてみた。
Pull Requestは読みやすさを意識して書く
多くの方が言っている通り、これが根底にあると思う。
当たり前のことだがチーム開発ではPull Requestの読み手が存在する。
それはレビュワーかもしれないし、他のチームメンバーかもしれないし、これから先に新しくチームにジョインするメンバーかもしれない。
そのため、読み手がわかりやすい文章を書く必要がある。
一方で、読み手が自分だけの（多くの場合）個人開発では、日記やメモのように適当に書いても問題ない。
開発者は自分だけなので、後から見返したときにやったことを思い出せればいい。
だから、適当に書いても問題はない。
しかし、チーム開発で個人開発のように書いてしまうと不都合が生じてしまう。
レビュワーのリソースを奪いかねないからだ。
レビュワーももれなく自分自身のタスクを抱えており、その合間を縫ってコードレビューをする。
そんなときにレビュイーしかわからない情報ばかりのPull Requestが送られてきたとしよう。
それを見てレビュワーは下記のようなことを思うはずだ。
「この部分は何を意図しているのだろう」
「ここはなぜこういう実装をしたのだろう？」
これらの疑問を解決するために、コードを見て、ロジックを考えて、タスクの内容を理解して、などの追加のタスクが発生してしまう。
レビューが数件ならいいかもしれないが、大量にレビューがきてしまうと回らなくなってしまう可能性が高い。
それゆえ、レビュイーが作成するPull Requestは、ある程度の品質を担保している必要があると思うのだ。
そのため、Pull Requestの作成者は読み手を意識した文章を書くことが大切で、レビュワーの負担をいかに軽減できるかを考えておくと良いということになる。
正直、レビューをしたことがない人にとっては意識しにくいかもしれない（自分も自分ごとにするのに時間がかかった）が、そのような意識がチーム全体に通底していると全体の生産性が上がると思う。
Pull Requestを作成するときに具体的に意識していること
さて、自分が意識していることを具体的にまとめてみる。
レビュワーが一目で理解できるかどうか
理解しにくいコメントはレビュワーのリソースを奪わうことにつながる。
そもそもPull Requestを読むことに時間がかかるし、読んだ後にレビューをするのでさらに時間がかかる。
そのためレビュワーはレビューに多くのリソースを割かなければならなくなる。
だから、レビュワーが理解しやすい簡潔でシンプルな内容で書いた方がいいと考えている。
理解しやすく、簡潔な内容であれば、レビュワーが要点を把握しやすくなるため、すぐレビューを実施できるようになる。
Pull Requestに記載する情報の精査
これもレビュワーのリソース削減につながると思う。
Pull Requestの内容は多すぎず少なすぎない丁度いい量の情報を記載するといい。
情報が少なすぎると、作成者に質問しなければならなくなり余分なコミュニケーションコストが発生する。
また情報が多すぎても読むのに時間がかかる。
そのため、少なすぎず多すぎない適度な情報量を記載することが求められる。
自分にしか分からない情報はないか
自分自身しかわからない情報はできるだけ書かないようにする。
これも余分なコミュニケーションコストの削減につながる。
できるだけ書かないことが理想だが、もしそのような情報を書きたい場合は詳細がわかるように追記しておくようにする。
実装で詰まった箇所があれば追記しておく
このようにしている人が多かったので真似してみた。
確かに、このように自信がない箇所を記載しておくとレビュワーがより注意深く見てくれるかもしれないなと思った。
定期的にレビュワーにコメントの可読性やわかりやすさなどのフィールドバックをもらい改良する
レビューはフィードバックをもらうためのものなので、積極的にフィードバックをもらって改善するように心がける。
Pull Requestに何を書くか
Pull Requestのテンプレートなどはネット上にたくさん転がっているのでそれらを見ながら取捨選択している。
特にPMやテックリードなどのレビュワーを担当されている方がまとめられている記事は、レビュワー視点で書かれているので非常に参考になるのでおすすめ。
自分がPull Requestに書いている内容は以下の通り。
タイトル
作成したPull Requestのタイトルを書く。
タイトルは「[ (内容) ] (チケット番号) ; (Pull Requestの内容)」というようにしている。
自チームはチケットをBacklogで管理しており、チケット名にキーを（(プロジェクト名)-(番号) ）を使用している（下記の例は、Developというプロジェクトの100番目のキー）。
たとえば、新しくログイン機能を追加したいという内容の100番のチケットを対応した場合、 [ add ] DEVELOP-100 : ログイン機能を追加した というように書く。
Prefixはコミットメッセージに付けているのでいらない気もするが一応付けている。
概要
プルリクエストの内容を簡潔に1～2行程度記載する。
Backlog
Backlogのリンクを記載する。
やったこと
今回のPull Requestで行った処理の内容を記載する。
箇条書きでもOK。
変更結果
作業前後の結果を表形式で記載する。
スクショを撮れる場合はスクショを結果欄に貼り付ける。
確認手順
レビュワーがどのような手順を踏むと作業結果を再現できるかを記載する。
共有事項
マージ後にコマンド操作が発生した場合など、チーム内で共有するべき事項があれば記載する。
備考
備考があれば記載する。
実装で詰まった部分があればここに記載している。
Prefix
使用しているPrefixの一覧。
厳格に定めても運用が面倒なのでゆるく運用にしている。
コミットメッセージにも同じPrefixを付けている。
- add：新しくファイルや機能を追加した場合
- fix：バグの修正を行った場合
- update：バグ修正以外の機能修正
- remove：ファイルや機能の削除
