はじめに
先日、私が参画中のプロジェクトは製造工程の真っ只中で、一日平均3~4件ほどのプルリクエスト(以下、PR)が作成されていました。
順調に進んでいるように見えた一方、レビュー工程に時間を要する課題が度々見られ、結果的に作業工数が逼迫する事態も発生してしまいました。
控えるタスクを捌いていくためにも、レビューに注ぐ工数はレビュイー・レビュワーにとってなるべく減らしたいものです。
ただ、品質を向上させるためにも他者レビューは重要であり、なるべくレビューはしっかり行いたいし見てもらいたい、、
そこで、今回はレビューにかかる時間を最小限にするための工夫として、レビューのしやすさ の観点で PR自体の品質 を向上させる考え方をまとめてみます。
実際にレビュワーさんから評価いただけたテンプレートも記載しますので、よければ活用してみてください！
この記事でわかること
- なぜレビューに時間がかかるのか
- PRをつくるときの考え方
- PRをレビューする人が何をみているのか
- PRのテンプレート
主な対象者
- PRレビュイー初心者・中級者
環境
- GitHub
- BitBucket, GitLabなどでもOK
前提
なぜソースレビューに時間がかかる？
まず、ソースレビューに時間がかかってしまうのは何故なのか、いくつか考えられる原因を挙げてみます。
- 実装が複雑で、処理を追いにくい
- 単純に変更量が多い
- 動作確認のため
- 変更による影響確認のため
- レビュイー↔︎レビュワー間のやり取り, etc…
「実装が複雑で」の場合は、より簡潔な実装にすればレビュー負担を軽減できそうです。（もちろん難しい場合もあります）
しかし、その他についてはどうしてもある程度の時間はかかる気がします。
中でも、レビュー指摘・FB対応を含めたやり取りは必ずといっていいほど発生します。
なぜこの変更を加えたのか、どのような影響があるのかなど、変更の背景・目的をレビュイーに確認するやり取りが長く続いていくと、両者への負担が大きくなってしまいます。
Why→How→What
ここで、PRのレビューを行う際にレビュワーが確認する内容を挙げます。
- PRのタイトル
- PRの向き先
- PRの説明
- コミット履歴
- 変更ファイル, etc…
コミット履歴や変更したファイルは、基本的にGitHub上で自動で一覧表示される一方、その他の項目はレビュイーがPR作成時に設定・記載すると思います。
プロジェクトによってはPRのテンプレートがある場合もありますが、どのような内容を記入するかはレビュイーによって揺れる部分でもあります。
ではここで、レビューのしやすいPRとは何でしょうか。
個人的には、そのPRにおける Why → How → What が明記されているものだと考えています。
- Why → なぜこのPRを作ったのか、なぜこの変更が必要なのか
- How → どのように対応したのか、どのように対応内容の確認ができるのか
- What → 何を変更したのか、何が解決されたのか、何が解決できていないのか、何に影響するのか
「なぜ」については、PRを作った背景を明らかにしたいので、対応する課題（Issue）の概要やリンクを明記するのが良いと思います。
例えば、PRのタイトルに課題NoやIssue番号を付与したり、PRの説明に概要を十分に書く方法があります。
「どのように」「何を/が」については、Markdown記法を活用して構造的に記入するのがよいと思います。
上記の内容をPRのタイトルや説明に記入することで、PRを見る人に詳細なコンテキストを共有できます。
成果物の背景の情報が豊富であれば、一目で何を行ったPRなのかが伝わりますし、その内容と実装に乖離はないかの観点でもソースコードレビューがしやすくなる効果が見込めます。
また、事前情報なしでプログラミング言語の読解を行うのと、自然言語で書かれた内容を踏まえて読解するのでは、圧倒的に後者のほうが進めやすいと思います。
以上のことから、PRには「なぜ」「どのように」「何を/が」を書いておくとよいと考えます。
実践
前提部分が長くなってしまいましたが、ここから実際にPRを作る際のテンプレートを紹介します。
PRのテンプレート
以下がテンプレ例です。
## 概要
<!-- 背景・目的を記載する。課題・タスクの内容を記載する。WBSやチケットのリンク、Issue番号などを記載する。 -->
## 変更内容
<!-- ファイル単位やコミット単位で変更内容を説明する。 -->
## 影響範囲
<!-- 本変更で影響のある機能・画面・テストを記載する。 -->
## 動作確認
<!-- 動作環境・確認方法を記載する。作業者の動作確認の結果を記載する。 -->
## レビュー観点
<!-- 重点的に確認が必要な点、不安な点など記載する。 -->
## 補足
<!-- 本PRで対応しないこと、申し送り事項など、本PRの変更差分に含まれない情報を記載する。 -->- 概要
- Whyに対応します。
- このPRを作った背景、実装したい機能などの目的を記載します。
- 関連する課題・タスクの内容を記載します。可能であれば、WBSやチケット、GitHubの場合はIssue番号などを明記します。
- 変更内容
- How, Whatに対応します。
- 変更内容をファイル単位やコミット単位で記載します。
- 余力があれば、ファイルパスや各コミットのリンクを貼ると辿りやすくなります。
- 細かいロジックの説明などはソースを読む方が効率的なこともあるので、概要説明程度に留めることが多いと感じます。
- 影響範囲
- Whatに対応します。
- PR内の変更により、ほかの機能・画面・テストに影響があれば記載します。
- ない場合は「なし」と明記するのも忘れずに。確認した証明になります。
- 動作確認
- Howに対応します。
- 動作環境と動作確認の方法を記載します。この手順通り操作するとPRの変更内容を確認できるようにするのが理想です。
- 動作確認の結果を記載します。
- バッチなどの場合、実行ログやテストログをコードブロックで記載すると良いです。
- 画面の場合、画像・動画を添付すると、実装者の環境で正常に確認できていることが主張できます。
- 例えば、レビュワー環境で表示崩れが発生したとき、実装が悪いのか、実行環境の差異が悪いのかの原因切り分けがしやすくなります。
- なお、画面キャプチャしてよい画面・機能なのか、キャプチャ内に機密情報はないか、キャプチャソフトの安全性など、セキュリティの意識も忘れずに。（無闇に撮って載せるのは厳禁）
- レビュー観点
- 実装にあたり不安な点、重点的に確認してほしい点を記載します。
- 補足
- 本PRで対応しないことや申し送り事項など、本PRの変更差分に含まれない情報を記載します。
期待できる効果
- PRを作った背景・目的がわかるので、変更の意図が伝わりやすい
- 動作確認方法がわかるので、レビュワー環境ですぐに再現しやすい
- 影響範囲がわかるので、変更によるデグレ発生懸念を検知しやすい
「なぜ」「どのように」「何を/が」が伝わっているため、レビュイー↔レビュワー間のやり取りを削減し、返答・確認待ちなどによる遅延対策の効果が期待できます。
まとめ
今回はレビューにかかる時間を最小限にするための工夫として、レビューのしやすさの観点でPR自体の品質を向上させる考え方をまとめてみました。
PRの説明欄にWhy→How→What（「なぜ」「どのように」「何を/が」）に紐づく情報を記載しておくことで、読み手の理解を深めることができると思います。
レビュイーとしては、実装を終えたところでさらに一手間加えないといけない点で少し面倒に感じるとは思います。
しかし、得られる効果は手間以上に大きいと個人的には思いますし、自身の成果物の理解を深めるという意味でも、習慣にすると良いのかなと思います。
副次的な効果として、新規参画者が過去の製造履歴を確認するときの手立てとなったり、数週・数か月後の未来の自分が振り返るときのドキュメントにもなるため、これまであまりPRに力を入れていなければぜひお勧めしたいです！
記載したテンプレートはあくまで一例ですが、プロジェクト内で記載ルールがない場合などに参考にしていただければと思います。
