Pull Request の書き方
はじめに
ウォンテッドリーでは書いたコードについて Pull Request を通じてレビューを受けることが必須になっています。 コードレビューは仕事を前に進めるためには避けては通れないという事実がある一方で、コードレビューで多くの時間を使ってしまっているケースや完全に作業が止まってしまっているケースを見ることがままあります。
コードレビューはレビュイー(reviewee)からレビュアー(reviewer)への仕事の依頼です。 レビュアーがパフォーマンス高く効率的にレビューができるか否かは仕事を依頼するレビュイーの段取りにかかっています。
本記事では Pull Request を作る際に心がけるべきポイントを紹介します。
小さい単位で Pull Request を作る
可能な限り小さい機能単位で Pull Request を作ったほうが素早く質の高いレビューを受けられることが多いです。 適切なまとまりを考えて、小さい Pull Request を出していくと良いでしょう。
なぜ小さい Pull Request を作るべきかについては Google のエンジニアリングプラクティスのページが非常にわかりやすく説明しているので、こちらも合わせて読んでみてください。 https://google.github.io/eng-practices/review/developer/small-cls.html
Why - Pull Request がなぜ必要なのかを辿れるようにする
経緯を全ての人が知っているとは限らないので Why の部分は必ず書きましょう。issue のリンクを貼っておくことで十分な場合もあります。後でこの PR を見た人が Why の部分を理解できるようにしておくことが重要です。 (それはレビュアーかもしれないし、後にバグを直す人かもしれないし、半年後の自分かもしれない)
一連の作業の中での位置づけを示す
小さい単位で Pull Request を作るべきということを書きましたが、そうなるとある機能を実装するためにいくつかの PR を分けて作成することが多くあります。 そのときに、依存関係がある一連の作業におけるこの PR の位置づけを示してあげると、レビュワーが文脈を理解しやすくなります。issue の側でタスクリストを作成し、「タスクの全体像は issue XXX を参照」のような書き方をすることもよくあります。
これは必ずしもすべての PR で行う必要はありませんが、テクニックとして覚えておくとよいでしょう。
What - 変更の内容を簡潔に説明する
What にはその PR で行った変更の内容を簡潔に記述してください。ここではコードの変更内容をただ列挙しただけのようなものは求めていません。それよりも、もう少し抽象的なレベルでどんな変更を行ったのかを記述するようにしてください。特に AI に PR の description を書かせると、よくない例のようになりがちなので気をつけてください。
よい例：
/demo_menu というパスでデモメニュー画面を追加し、そこからオンボーディングデモの起動が行えるようにした。 また、ホーム画面のコンテンツの最下部にデモメニューへの導線を追加した。
デモメニューは本番環境以外でのみアクセスできる。
よくない例：
/demo_menu のルーティングを追加
DemoMenuController に index アクションを追加
XXX に YYY を追加
...
また、画面の変更を行った場合はスクショや動画を貼るようにしてください。そうすることで、レビュワーがどんな変更が行われたのかを理解しやすくなります。変更前と変更後の両方のスクショを貼るとよりわかりやすくなることもあります。
何を動作確認したのかを記載する
まず前提として、行った変更が動作することを確認するのはレビュワーではなく、PR を作る側の仕事です。レビュワーが「この変更はそもそもちゃんと動いているのだろうか」と疑問を持ちながらレビューをすることにならないよう、どのような動作確認を行ったのかを記述してください。
画面で操作する機能の場合は、動作確認をした動画を貼るのが一番いいです。一方、純粋なバックエンドのみの実装の場合は、適切なテストが書かれていれば、動作確認の記述は必ずしも必要ではありません。
レビューで確認してほしい観点を記載する
これも必ずしも毎回やる必要はありませんが、こういう観点でレビューしてほしいというものがあれば、それを書いておきましょう。
例：
クラスの責務の切り方（XX に YY を持たせている点）が妥当か
実装方法に自信がないので、もっといい書き方があれば知りたい
また、設計自体に不安があればコードを書き始める前にレビュアー(となる予定の人)と適切にコミュニケーションを取って事前に設計方針を固めておきましょう。 ほとんどコードを書いてしまってからレビューの段階で設計自体の問題点を指摘された、かつそれがコードを書く前でも問題を指摘可能だった場合に大きく無駄を生んでしまいます。
適宜レビューがしやすくなるような補足コメントを入れる
What には変更のサマリーを記載しますが、適宜個別の箇所にも補足説明を入れると、レビューがよりしやすくなることがあります。
ただし、その情報が PR のレビュワーだけでなく将来の開発者にとっても有益な情報なのであれば、それは PR 上でコメントを入れるのではなく、コードに直接コメントで書くようにしましょう。例えば何か理由があって特別な処理をするコードを書いた場合には、そのような処理を行っている理由をコード上のコメントに残しておくべきです。
AI レビューの指摘は resolve しておく
ウォンテッドリーでは PR を作成すると Devin Review などのAIレビューが自動で走るようになっています。AIレビューはコードの不具合などを精度高く指摘してくれ、今や開発プロセスに欠かせない存在になっています。
AIレビューの指摘については、チームメンバーにレビューを依頼する前に、以下を行っておきましょう。
まず本当に対応する必要があるかを判断する
対応する必要があると判断した場合には、対応して、指摘コメントを resolve する（多くの場合、修正 commit を積むとAIが修正されたことを検知して勝手に resolve してくれます）
対応する必要がないと判断した場合には、そう判断した理由（実際には〜〜なのでその問題は発生しない、かなりレアケースなのでそこまではやらなくてよいと思った、など）をコメントしてから resolve する
妥当な指摘に対して無言 resolve はしないようにしましょう。
もっと知りたい
最終更新