ADRに残すのは結論より、捨てた案と制約

記録は、コードの隣に置く

最後に、記録をどこに置くかの話です。このプラグインでは、ADRをコードと同じリポジトリの docs/adr/ フォルダに置いています。社内の共有ドライブや、別のドキュメントサービスではありません。

コードの隣に置く理由は、変更と同じ差分で記録を直せるからです。共有先の書き方を変えたときは、コードの変更と ADR-0002 の追加を、同じプルリクエストに入れました。レビューする人は、何を変えたかと、なぜ変えたかを、同じ画面で読めます。別の場所に置くと、記録の更新はどうしても後回しになり、やがて忘れられます。Nygard も、決定の記録をプロジェクトのリポジトリに置くことを勧めています。

ADRを読むときの4つの問い

書いた記録が本当に役に立つかは、読む側の目で確かめられます。自分の書いたADRを、次の4つの問いで読み直してみてください。

判断を縛った目的と制約が書いてあるか。選ばなかった案と、その理由があるか。良いことだけでなく、引き受けた負担も書いてあるか。どの前提が変わったら開き直すかがあるか。4つとも「はい」なら、半年後の自分にも判断を渡せます。逆に、決定の欄しか埋まっていないなら、それは1ページ目の「結論だけのメモ」と変わりません。

手を動かして確かめる

今回は、書き起こしてみるのがいちばんの練習です。手元のコードで、「なぜこうなっているのか、もう思い出せない」判断を1つ選んでください。大きな判断でなくてかまいません。ライブラリの選び方、フォルダの分け方、設定ファイルの形式。どれも立派な判断です。

選んだ判断を、図の6つの欄で書き起こしてみましょう。書けない欄が出てくるはずです。とくに「検討した選択肢」と「見直す条件」は、あとからでは書けないことが多い欄です。宿題：理由を思い出せない判断を1つ選び、6つの欄で書き起こす。書けた欄と書けなかった欄は、このラベルからコメントに残せます。

ADRの原典は、Michael Nygard によるDocumenting Architecture Decisions（2011）です。「検討した選択肢」などの欄を足したひな形はMADR、軽量なADRを勧める立場は ThoughtWorks のTechnology Radarで読めます。

まとめと、次回

第3回のまとめです。結論だけのメモは、理由を運びません。理由が消えても形は残り続け、記録が無いとそれが名残だと気づけません。ADRは、1つの判断を短い欄で残す文書で、厚く書くべきなのは結論ではなく、捨てた案と、判断を縛った制約です。捨てた理由が残っていれば、同じ議論を前回の続きから始められます。見直す条件は決めたときに書き、覆した判断は消さずに置き換え、記録はコードの隣に置く。今回読んだ2件の記録は、どちらもこの形で書いてあります。

次は、いよいよ第2章に入ります。連載2.1「SRP と OCP ――共有先を一つ足したときの差分を追う」です。1.2で数えた差分を、今度は設計の原則の目で読み直します。今回の2件の記録が、その差分のどこに効いているかも確かめていきます。それでは、次回もお楽しみに！

連載の全体像は本編の連載目次へ。前回の1.2「共有先が増えても触らないコードを決める」、前々回の1.1「共有・保存・計測は、なぜ同じ責務にしないのか」とあわせて読むと、責務の分け方から記録の残し方までが一続きになります。

プロマリでは、Webサイトの制作に加えて、共有や計測のような「裏側のしくみ」の設計・導入、それらを運用できる人材の育成に取り組んでいます。設計の判断をチームで残す仕組みを整えたい方も、お気軽にご相談ください。

Web制作・計測・人材育成のご相談はこちら ↗