プルリクエストに書籍の引用を添える習慣

この記事は約 4 分で読めます。

「なぜこう設計したのか」に答える

プルリクエストのレビューで「なぜこの設計にしたのですか？」と聞かれたとき、明確に答えられるでしょうか。「なんとなく」「前にもこう書いたから」では、レビュアーを納得させられません。

設計判断の根拠として書籍の引用を添える習慣をつけると、この問題が解消します。「Martin Fowler のリファクタリングで紹介されている Replace Type Code with Subclasses パターンを適用しました (第 12 章)」と書くだけで、設計の意図が明確になり、レビュアーも判断しやすくなります。

引用の書き方

プルリクエストの Description に、以下のフォーマットで引用を添えます。

## 設計判断の根拠

この PR では Repository パターンを導入してデータアクセス層を分離しています。

> 参考: 『Clean Architecture』Robert C. Martin, 第22章
> 「ビジネスルールはデータアクセスの詳細を知るべきではない」

テストでデータベースをモックに差し替えられるようになり、
テスト実行時間が 12 秒 → 2 秒に短縮されました。

ポイントは 3 つです。書籍名と章番号を明記すること。引用は 1〜2 文に絞ること。そして、引用だけでなく実際の効果も併記すること。

この習慣がチームにもたらす効果

設計語彙が揃う

チームメンバーが同じ本の同じ概念を参照するようになると、設計に関する議論の精度が上がります。「あの PR で引用されていた Repository パターン、今回のケースにも使えそうですね」という会話が自然に生まれます。

暗黙知が形式知になる

ベテランエンジニアの頭の中にある設計判断の基準は、普段は言語化されません。引用を添える習慣があると、「なぜこう判断したのか」が PR の履歴として残ります。新しいメンバーが過去の PR を読むだけで、チームの設計思想を学べるようになります。

読書のモチベーションが上がる

他のメンバーの PR に書籍の引用が添えられていると、「自分もその本を読んでみよう」という動機が生まれます。強制ではなく、実務の文脈で本が紹介されるため、読書への抵抗感が低くなります。

引用に適した場面

すべての PR に引用を添える必要はありません。以下の場面で特に効果的です。

設計パターンを新たに導入したとき。なぜそのパターンを選んだのか、どの本のどの章を参考にしたのかを書きます。

リファクタリングを行ったとき。変更の動機と、適用したリファクタリングパターンの名前を書きます。

パフォーマンス改善を行ったとき。計測結果とともに、最適化の方針を参考にした書籍を記載します。

設計に関する本を 1 冊読んでいれば、引用のネタには困りません。

注意点

引用は権威付けのためではなく、コミュニケーションの道具として使います。「この本にこう書いてあるから正しい」という使い方は逆効果です。あくまで「この本のこの考え方を参考にして、こう判断しました」という文脈で使ってください。

また、引用する本はチーム内で広く知られているものが理想です。誰も読んでいないマイナーな本を引用しても、共通言語としては機能しません。チームの本棚に 1 冊置いておくと、引用された本をすぐに確認できて便利です。

関連記事

• Pull Request が通らない人に足りないのは、たいてい語彙力
• 技術書の内容を実務に活かす方法 - 読んで終わりにしない

まとめ

プルリクエストに書籍の引用を添える。たったこれだけの習慣で、設計判断が明確になり、チームの設計語彙が揃い、読書の動機が生まれます。次の PR で、設計の根拠として本の章番号を 1 つ添えてみてください。