derive-instead-of-transcribing

システム内の2箇所が同じ情報を保持している場合に当てはまる。設定とそのドキュメント、スキーマとそのクライアント型、パレットとそれを使うサイト、コマンド一覧とリファレンスページなど。

2つ目のコピーが意図的に異なる内容である場合には当てはまらない。丁寧に作られた入門ガイドはリファレンスの古びたコピーではなく、別の役割を持つ文章である。

1. どちらをソースとするかを決める。通常はプログラムが実行時に実際に読み取る方だ。
2. もう一方を生成し、差分がレビュー可能なように生成ファイルをコミットする。
3. 再生成を行い、コミット済みのコピーと差異があれば失敗するCIステップを追加し、エラーメッセージには実行すべき正確なコマンドを含める。
4. 生成ファイルに、それがどのバージョンまたはコミットから生成されたかを刻印し、読み手が何を説明しているものかを分かるようにする。

誰にも読めない生成成果物では目的が果たせない。出力が機械にしか意味を持たないなら、レンダリング層が必要になり、それは維持すべきコードがさらに増えるということだ。

結合コストもある。消費側は生産側の形に依存するようになり、片方でのリファクタリングがもう片方のビルドを壊す。それは通常むしろ狙い通りなのだが——つまりゲートは満たしやすくしておかねばならない、さもなければ誰かが無関係なリファクタリングの最中にそれを無効化し、そのまま忘れてしまう。