レビュアーの負荷を軽減して、コードの品質をチームで高めるためのプルリクエストテンプレート活用

ちょっと社に入ってから、レビューをしたり、してもらう機会が増えました。
1人で完結させるよりもブラッシュアップできますし、単純にコミュニケーションを取れる楽しさも感じています。
その反面、レビューに時間がかかりやすく、全体の工数が膨らんでしまう課題もあります。

レビューの負荷軽減と質の高い議論をするために、プルリクエストテンプレートがとても効果的だと感じているので、その理由と私が使っているテンプレートの内容を紹介します。

プルリクエストテンプレートを使うメリット

• 実装者の内省を促して、レビューを依頼する前の品質を高める
• レビューする観点や背景情報を整理して、レビュアーの負荷を減らす
• あとで変更する際の判断材料として使う

実装者の内省を促して、レビューを依頼する前の品質を高める

作業をしていると近視眼的になりがちで、客観的に考えることが難しくなります。
レビュアーや利用者から見るとどうなんだろう？と視点を変えてみると、足りないことや工夫できることが見つかるかもしれません。
「戦略の失敗は戦術では取り返せない」と言われますが、主観と客観、具体と抽象を行き来するためのトリガーにプルリクエストテンプレートが役にたつと考えています。

レビューする観点や背景情報を整理して、レビュアーの負荷を減らす

レビューをするって思っているより時間がかかるものです。
実装者が作業をしながら得た情報や考えたことをレビュアーに伝えることで、その負荷を減らすことができるようになります。実装者と同じように調べ物をさせてしまったり、「どんなことを考えて実装してのかな」と想像させてしまうと、時間がいくらあっても足りなくなってしまうからです。

コードレビューをするのであれば、レビューがしやすい状態に整えるのも実装者の役割だと考えています。

あとで変更する際の判断材料として使う

「ドキュメントがなくてもコードを読めばわかる」は理想ですが、経験の差や得意分野の違いもあるので、うまくいかないことも多いです。

「理想的だけど難しいこと」は避けて、「少し時間はかかるけど単純なやり方を選択する」のも、チームの役にたつ行動だと考えています。

登録しているプルリクエストテンプレート

少し長いですが、次のようなテンプレートを使うことが多いです。

<!-- 記載することがなければ、未記載か見出しごと削除してください -->

## URL

<!-- チケットやデザインデータ、参考ページなどのURLを記載してください -->

-

## 利用者は何ができるようになって、何ができなくなりましたか？

<!-- どんな背景や問題があって対応をして、それは利用者にとってどんな役に立ちますか？ -->

-

## 具体的にどのような変更がありますか？

<!-- レビューする際に把握すべき変更箇所を教えてください -->

-

## あえてやっていないことはありますか？

<!-- レビュアーが考えなくてもいいことを教えてください -->

-

## どのような動作確認をしましたか？結果はどうでしたか？

<!-- どんなページや機能に対して、どのような手順で確認をしましたか？どのようになっていれば正常とみなせますか？ -->

-

## とくに気をつけてレビューして欲しいところはありますか？

<!-- 不安なところ、複雑で見落としがありそうなところはありますか？ -->

-

## その他

<!-- 上記の項目に当てはまらないもの、どこに書けばいいか判断できないことはありますか？ -->

-

## スクリーンショット

<!-- 変更箇所を見比べられるように画像やアニメーションGIFを貼り付けてください -->

| 説明 | スクリーンショット |
| ---- | ------------------ |
|      |                    |
|      |                    |
|      |                    |

| 説明 | 変更前 | 変更後 |
| ---- | ------ | ------ |
|      |        |        |
|      |        |        |
|      |        |        |

URL

## URL

<!-- チケットやデザインデータ、参考ページなどのURLを記載してください -->

チケットやデザインデータ、実装の参考にしたページのリンクをリストアップします。
レビュアーも探せるかもしれませんが、実装時に開いているのであれば、そのまま転記したほうが全体的な効率は良くなりますよね。

利用者は何ができるようになって、何ができなくなりましたか

## 利用者は何ができるようになって、何ができなくなりましたか？

<!-- どんな背景や問題があって対応をして、それは利用者にとってどんな役に立ちますか？ -->

利用者目線での効用や便益を整理します。いわゆるUXの向上といった側面ですね。
たとえば「機能を追加したことで、利用者はどのような嬉しいことがあるんだろう？」と少し考えて、それを言葉にしてみます。

「どれだけ利用者のことを考えているか」の積み重ねが、エンジニアとしての成長や貢献実感につながるのだと感じています。

具体的にどのような変更がありますか？

## 具体的にどのような変更がありますか？

<!-- レビューする際に把握すべき変更箇所を教えてください -->

コードから機能を推測してもいいですが、その前に「こんな機能を追加しました」「こんな変更点があります」と大枠を伝えてくれたら、コードリーディングがもっと楽にできると思います。

あえてやっていないことはありますか？

## あえてやっていないことはありますか？

<!-- レビュアーが考えなくてもいいことを教えてください -->

プルリクエストのスコープ外のことがあれば記載しておきます。
あとからやろうと思っていることや、あえてスコープ外にしていることをレビュアーが考えてしまうのは効率がよくないからです。

それに、いろいろなことを一緒に考えると複雑になって負荷がかかりやすくなってしまいます。なるべく単純に、1つずつレビューしていったら、全体のレビューが終わっていた。そんな進め方が理想的と考えています。

どのような動作確認をしましたか？結果はどうでしたか？

## どのような動作確認をしましたか？結果はどうでしたか？

<!-- どんなページや機能に対して、どのような手順で確認をしましたか？どのようになっていれば正常とみなせますか？ -->

このプルリクエストの完了状態をできるだけ明確にしておきます。推測させないことが大切です。
テストケースがあれば、レビュアーも同じように操作をして正常であることをダブルチェックできます。
もう少しカジュアルな動作確認の場合でも、確認方法のヒントがあるだけでレビュアーの負荷は大きく下がると考えています。

とくに気をつけてレビューして欲しいところはありますか？

## とくに気をつけてレビューして欲しいところはありますか？

<!-- 不安なところ、複雑で見落としがありそうなところはありますか？ -->

「今回はこういう実装にしてみたけど、適切か判断できていない」「仕様がそもそも複雑なので、見落としがあるかもしれない」と感じたことはないですか？
レビュアーはまっさらな状態で確認するので、このような不安を客観的に見ることができます。
正直に不安なことを書いてしまいましょう。改善点が出てくれば儲けものですし、何もなければ問題ないと安心することができるからです。

その他

## その他

<!-- 上記の項目に当てはまらないもの、どこに書けばいいか判断できないことはありますか？ -->

相談ごとを書くこともありますが、基本的には書かずに終わることも多いです。
頻度は高くないですが、項目として置いておくと便利です。

スクリーンショット

## スクリーンショット

<!-- 変更箇所を見比べられるように画像やアニメーションGIFを貼り付けてください -->

| 説明 | スクリーンショット |
| ---- | ------------------ |
|      |                    |
|      |                    |
|      |                    |

| 説明 | 変更前 | 変更後 |
| ---- | ------ | ------ |
|      |        |        |
|      |        |        |
|      |        |        |

文章で説明するより画像や動画のほうが伝わりやすいこともあります。
プルリクエストの全体像を掴む際にも、前後のスクリーンショットがあると理解しやすくなります。

https://zenn.dev/chot/articles/8d2b0e6e0f7741

まとめ

• レビュアーに情報を探せず、アクセスできる状態にしておく
• レビュアーに推測させず、やったこともやっていないことも記録しておく
• 第三者の視点から見直して、レビュー提出前の品質を高めておく

この3つを意識しておくと、レビューの全体的な効率が上がり、本当に必要だった議論にフォーカスができるようになると思います。