keeping-one-source-of-truth

信頼できる唯一の情報源を維持する

必須の前提知識： principal-engineering スキル。

概要

システムに関するすべての事実は、必ず一か所だけに存在し、システムのそれ以外のすべての部分は、その場所から情報を読み取ります。これは利便性よりも優先されます。

原則

1. データを追加する前に、すでにどこがそれを管理しているかを確認します。 その管理元を拡張し、競合するものを新たに作らないでください。
2. 保存するのではなく、導出します。 プラットフォームや既存の情報源から読み取り時に取得できるなら、そこから読み取ります。古くなる可能性のある別の情報源に回答をコピーしないでください。
3. 作業中に見つけた重複を解消します。 既存のファイルに記載済みの内容をコードにハードコードしている（またはその逆の）箇所を編集する際は、その作業の一環として統合し、3つ目の表現を残さないでください。
4. 項目が見つからない場合は、明示的に失敗させます（handling-failures を参照）。単一の情報源が信頼できるのは、そこに情報がない場合にエラーとなり、黙ってデフォルト値が使われない場合に限ります。
5. 生成物か手編集かを明記し、生成物は編集しません。 すべての成果物に、どちらであるかを記載します。
6. 語彙は型で管理し、文字列で曖昧に管理しません。 コードの分岐に使う識別子、種類、状態、名前は、定数、列挙型、シールド型、またはレジストリエントリにします。同じ文字列を2回書けば、タイプミスが入り込む余地のある2つの情報源が生まれます。
7. 2つの情報源が食い違う場合は、それを明示します。 矛盾を表面化させることが、最初に行うべき修正です。完全な修正では、どちらの値が有効かを判断し、情報源を1つにまとめ、採用しない方を削除します。どちらか一方を黙って使わないでください。それでは、たまたま先に読んだ回答に矛盾を取り込んでしまいます。重要な経路上で食い違いが発生した場合は、追跡項目を登録するだけでなく、担当者に直接連絡します。誰も読まないチケットでは、問題は表面化しません。

境界

• キャッシュと読み取りモデルは、導出が自動で、古さが制限され、監視可能であれば、正当な派生コピーです。このルールで禁止するのは、人が手作業で同期を維持するコピーです。
• テストフィクスチャでは、意図的に現実のコピーを固定できます。それがフィクスチャであることを示すラベルが、その役割を伝えます。
• ドキュメントにも同じルールが適用されます（インデックスは案内するだけで、判断はしません）。技術ライターのプラグインがインストールされている場合は、その側面を technical-writing スキルが担います。

よくある間違い

• 閾値、URL、マッピングを「一時的に」コピーすること。一時的なコピーも、その上に書かれた TODO と同じ期間だけ残ります。
• thing をそのまま編集せず、隣に thing-v2 を作成すること。
• 設定ファイルの値を隠すデフォルト値をコードに置くこと。設定を変更しても何も起きない場合、その原因はこれです。
• 同じ状態を表す列挙型を、2つのサービスでそれぞれ定義すること。一方に新しい状態が追加された日、その境界で気付かないうちに除外されるようになります。