Pull Requestはドキュメントだよ
半年くらい前から、Pull Request は立派なドキュメントであり、正しく記録として残すことに力を入れている。
こと「ドキュメント」となると、Esa や Notion、GitHub Issue といったドキュメントツールに ADR(アーキテクチャ決定の記録）やシステム設計、プロジェクトについての内容を書くことを考えがちになるが、Pull Request も立派なドキュメントであり、気を払う対象である。
Pull Request は、「ある目的を達成するために必要だったコード変更の差分を一定の基準でまとめたもの」という前提から、先に述べたドキュメンテーションと比較するとコードレビューのための一過性のものであるという印象を持ちやすい。真面目に職業エンジニアをしていれば、概要欄に大元の情報源となるドキュメントの URL がペタリと貼っただけ（もしくはそれすらない！）、という Pull Request を見たことや書いたことがあるのではないだろうか。
「ソフトウェアエンジニアリングとは時間で積分したプログラミングである[1]」という立場に立つと、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 の説明を求められるのがもっと面倒だと思うと、内容を充実させるモチベーションが湧いてくるのではないだろうか。
というわけで、怠惰のために勤勉に行き着いてしまった。怠惰も一苦労だ。
参考
-
[Google のソフトウェアエンジニアリング ― 持続可能なプログラミングを支える技術、文化、プロセス, O'Reilly Japan, p3] ↩︎
Discussion