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

こんにちは、プロマリの紫です。連載「丸いボタンの裏側」の第3回です。前回は、共有先が増えても触らないコードを先に決め、共有先の違いを名札カード（共有先ごとの TOML ファイル）へ寄せた設計をたどりました。その最後に「実際の決定記録を題材に、記録の残し方を見ていきます」と予告しました。今回はその約束を果たす回です。テーマは設計の記録に残すべきなのは、結論よりも、捨てた案と制約であるということ。このプラグインで実際に書いた2件の決定記録を、1行ずつ読んでいきます。

点線の付いた用語は、その言葉を押すと詳しい説明が開きます。意味、身近なたとえ、この実装での使い方を順に読めます。キーボードではTabで用語へ移動し、EnterまたはSpaceで開き、Escapeで本文へ戻れます。各ページで最初に出る用語から参照できるようにしました。

この記事は連載「丸いボタンの裏側」の第3回（1.3）です。前回の1.2「共有先が増えても触らないコードを決める」で、名札カードへ寄せた設計を先に読むと、今回の2件目の記録がぐっと読みやすくなります。連載全体の地図は、本編5ページ目の連載の目次からどうぞ。

結論だけのメモは、理由を運ばない

少し想像してみてください。あなたはこのプラグインの開発に、途中から加わったとします。コードを読んでいると、共有先ごとにPHPのクラスが1つずつ並んでいます。どうしてPHPなのだろう、と思って資料を探すと、見つかったのは「共有先はPHPのクラスで書く」という1行のメモだけでした。

このメモは、間違ったことは何も言っていません。ただ、なぜそう決めたのかを運んでいないのです。理由が分からないと、その判断をいつ見直してよいのかも分かりません。変えてよいのか、変えると何かが壊れるのか。確かめる手がかりがないので、たいていの人は「触らないでおこう」と判断します。こうして、理由の分からない形が残り続けます。

設計の判断を、理由ごと1件ずつ残しておく文書があります。それがADRです。今回は、この短い文書に何を書けば後から役に立つのかを、実際の記録を使って確かめていきます。

理由は、状況が変わると見えなくなる

先ほどのメモは、たとえ話ではありません。このプラグインで実際に起きたことです。プラグインのCHANGELOGをさかのぼると、流れは次のようになっていました。

はじめのころは、WordPressのPHPがボタンを描き、共有画面のURLも組み立てていました。この時期には、共有先をPHPのクラスで書くことに、はっきりした理由がありました。PHPが実際にそのクラスを使って、URLを作っていたからです。

その後、URLの組み立てをブラウザ側の1か所へ移しました。前回見た ShareDestination がそれです。すると、PHPのクラスは「どこへ何を送るか」を並べるだけの宣言に縮みました。WordPressは実行時にそのクラスを読み込まず、生成器が正規表現で文字を拾うだけになっていたのです。PHPで書く理由は、この時点で消えていました。けれど、理由がどこにも書かれていなかったので、誰もそれに気づきませんでした。

名残に気づいたのは、共有先の定義を見直していたときです。PHPとして正しい書き方（定数や文字列の連結）をしても、生成器だけが止まってしまう。実行されないので、PHPの型の検査も効いていない。そこで初めて「このクラスは、もう何のためにもなっていない」と分かり、共有先を名札カードで宣言する形へ直しました。理由が消えても、形は残り続ける。記録が無いと、それが名残だと気づくまでに時間がかかります。