PRテンプレートの「レビュイーだけに伝えたいこと」をHTMLコメントで書いてレビュー負荷を下げるテクニック

GitHubでPull Requestを作る際、「必ずPRに書いて欲しいこと」をPRテンプレートに書くプラクティスが普及している。 PRテンプレートを用意する際に「レビュイー (PR作成者) だけに伝えたいこと」をHTMLコメント ( <-- aaaa --> ) として書くと余計な情報をレビュアーに見せずに済むテクニックがあるので紹介する。

Pull Requestテンプレート

GitHubでホストするgitリポジトリ内に pull_request_template.md という名前のMarkdownファイルを用意しておくと、開発者がGitHub上でPRを作成しようとしたときにそのファイルの内容がDescriptionのデフォルト値として入力される仕組みがある。

docs.github.com

PR Descriptionに何を書くかはチーム開発においてとても重要で、何を書くべきで何を書かないべきかについて議論したり、ルール化しているチームは多いと思う。この機能を使うことでうっかりPRに記載し忘れていて「チケット番号を必ず記載するルールになっているので明記して下さい。」というような非生産的やり取りを無くすことが出来る。

PRテンプレートが成長すると起きる課題

PRには「作る人（レビュイー）」と「見る人（レビュアー）」が居る。 PRテンプレートには二種類の人間それぞれに読んでもらうべきメッセージを含める必要があるが、愚直に (工夫せずに) 記載するとどうしても情報量が多くなってしまう。

PRのレビューでは動作の正しさはもちろんコードの読みやすさや設計の良し悪し、パフォーマンス、セキュリティなど様々なことを考慮する必要があり、レビュイーの負担は大きい。そのままでは長大なPR Descriptionをレビュイーが「このメッセージは自分に関係があるのか？」を考えながら読まねばならない。

レビュイーだけが気にしていれば良い情報はレビュアーにとってノイズであり、そのままにすると生産性が下がる。

レビュイーだけへのメッセージはHTMLコメントで書く

GitHubのPull RequestにはHTMLコメントを記載できる。HTMLコメントとして書かれている内容は当たり前だが、PR作成 (編集) ページ以外では表示されない。

docs.github.com

この仕様を利用してレビュイーにだけ伝えたいメッセージ (例えば各項目に何を書いて欲しいかの説明) をHTMLコメントで記載することで、 レビュイーに必要なメッセージを伝えつつ、レビュアーが受け取る情報量を減らすことが出来る。

pull_request_template.md例:

# 概要
<!-- このPRは「何のために」「どういう変更をする」ものか、簡潔に説明して下さい -->

## 関連チケット
<!-- 関連するチケットがある場合はリンクを貼って下さい -->
* 

# 特筆事項
<!-- 参考にした資料、補足説明しておきたい背景などがあれば記載して下さい -->

----

※ :bulb: [コードレビューの目的と観点](https://github.com/pinkumohikan) についてもご確認下さい

PRページでの表示例 (レビュアー視点):

想定質問

Q: そんなに頑張らなくてもレビュアーが頑張って読み飛ばせば良くない？

A: Perl開発者のLarry Wallが提唱した「プログラマ三大美徳」の「怠惰」を愛しなさい。少しの工夫で仕組みによって解決できるのに、わざわざそれをやらない理由は無いだろう。

Q: PRテンプレートにはそのまま書いて、レビュアーが気しなくていいことはレビュイーがPR作るときに消す運用にすれば良いんじゃない？

A: Perl開発者のLarry Wallが提唱した「プログラマ三大美徳」の「怠惰」を愛しなさい。そういう運用をしていたところをいくつか知っているが、期待通りの運用がされていたのは導入直後だけだったので個人的にはそれでは回らないと思っている。かなり強い気持ちで警察業 (ルールを守らない人を指導しまくる役) をするならばあるいは。