Pull Requestはドキュメントだよ

この文章は自戒のために書かれたものである。

半年くらい前から、Pull Requestは立派なドキュメントであり、正しく記録として残すことに力を入れている。

こと「ドキュメント」となると、EsaやNotion、GitHub IssueといったドキュメントツールにADR(アーキテクチャ決定の記録）やシステム設計、プロジェクトについての内容を書くことを考えがちになるが、Pull Requestも立派なドキュメントであり、気を払う対象である。

Pull Requestは、「ある目的を達成するために必要だったコード変更の差分を一定の基準でまとめたもの」という前提から、先に述べたドキュメンテーションと比較するとコードレビューのための一過性のものであるという印象を持ちやすい。真面目に職業エンジニアをしていれば、概要欄に大元の情報源となるドキュメントのURLがペタリと貼っただけ（もしくはそれすらない！）、というPull Requestを見たことや書いたことがあるのではないだろうか。

「ソフトウェアエンジニアリングとは時間で積分したプログラミングである¹」という立場に立つと、Pull Requestはドキュメントとして、先の未来でも役にたつ情報源となっていなければならない。

開発者があるコードに変更を加えようとして、既存コードに不明点があったとする。理由を探るためにgit blameをしたときに、数年前のビックバンPull Requestに行き着いて、その概要には「なぜ・なに」が書かれておらず意図を読み取れず途方に暮れてしまう、と言う事態は往々にして起こりうる。

なぜこのようなことが起こるのか。理由は様々だが

• プロジェクト立ち上げ期や急成長期
• その時のチームメンバーとはPull Requestには残らない形でコミュニケーションをしていた
• 面倒だった

などがよくあるのではないだろうか。

Pull Requestを書くときに気を払うこと

具体的にPull Requestをどのように残していくのかについて考えてみる。ドキュメンテーションの技術論を紹介できるほど、私はできたエンジニアではないので、あくまで私が手探りで、Pull Requestを書く時に気を払っていることを書いてみる。

• Pull Requestはひとつの目的につきひとつにする
• 概要欄には「何をやったのか」を簡単に書いたあと、「なぜ」を自分の言葉で書く。背景となるドキュメントがあれば、そのリンクを「何のためのドキュメントなのか」とともに添付する
• レビュー時の議論点は、必ず「どう着地したか」をコメントで残す。
  • 新たなIssueとして残したのか、一旦保留とした、のかなど。
  • 保留することは全然問題ない。なぜ保留としたのか（単純にリソースがない、思いつかなかった、ちょいめんどくさそう、等）を少しでも残しておくとより良い。後から見た開発者が納得感を持てる。
• Pull Requestの概要欄にない差分をサイレントで含めない
  • あとから入れた変更点については必ずコメントか概要欄に残す

ざっと書いてみた。ごもっともだなと思いつつ、毎回のPull Requestでちゃんと書けているかと言われるとできていないことが多い。

Pull Requestをちゃんと書くことの難しさ

単純に知的体力の勝負なのだと思う。私が観測してきた「この人は本物だ」と思うエンジニアのPull Requestを見てみると、やはり期待を裏切らず皆ちゃんと書いている。

最近ではPull Requestのテンプレート機能や、GitHub Copilot Pull requestによる概要自動生成など、書くことを補助してくれるツールはたくさんある。それでも「なぜ」については自分で書く必要はあるが。

これらのツールが普及する時代において、できない理由は単純に知的体力を使う「書く」行動が面倒くさい以外にほぼないだろう、と個人的には思う。わかる。面倒くさいが、あとから「これはなにをやっているの？」とPull Requestの説明を求められるのがもっと面倒だと思うと、内容を充実させるモチベーションが湧いてくるのではないだろうか。 というわけで、怠惰のために勤勉に行き着いてしまった。怠惰も一苦労だ。

参考

• ドキュメントに固執せよ - gfnweb
• ドキュメントを書く時に考えていること - Kanmu tech blog