理由を書き留めよ

ドキュメント、特にソフトウェアの設計自体についてのドキュメントの価値については、ソフトウェア開発コミュニティの中でも議論が分かれています。反対派の論拠は、まず「目の前の設計」をすることの価値を強調するものと、変化し続けるコードベースに対して設計文書を同期させていくことの難しさを指摘するものが多いようです。

しかし、あまり労力を必要とせず、ほとんどかならずコストに見合う効果を期待できるドキュメントがあります。それは、ソフトウェア・アーキテクチャーに関連する意思決定の理由を記録するというもので、古くから使われています。

マーク・リチャーズの「22 アーキテクチャーではトレードオフは避けられない」で指摘されているように、ソフトウェア・アーキテクチャーとは、コスト、稼働日、さまざまな品質属性、その他の要素から適切なトレードオフを選び出してくることです。あなた自身を初めとして、マネージャー、デベロッパー、その他の開発関係者は、別のソリューションではなくそのソリューションが選ばれた理由やどのようなトレードオフが含まれているかを明確に理解していなければなりません。ハードウェアとライセンス料の削減のために水平スケーラビリティを犠牲にしたとか、セキュリティを保つこが非常に重要なので、応答時間を犠牲にしてもデータを暗号化することにしたといったことです。

このドキュメントの正確な形式は、プロジェクトの性格によって、テキスト形式の走り書き、ウィキ、ブログのような単純なものから、個々のアーキテクチャー上の決定をすべて記録するために形式を定義したテンプレートまでさまざまなものが考えられます。形式がどうであれ、ドキュメントは、「決定の内容は何か」、「なぜそのような決定をしたか」という基本的な問いに答えるものでなければなりません。副次的な問いですが、「他にどのようなソリューションを検討し、なぜ、選ばなかったか」、つまり「なぜ私の案ではいけないのか」についても、記述しなければならない場合がよくあります。ドキュメントは、検索可能にして、必要なときに簡単に見つかるようにすべきです。

このドキュメントは、次のような状況でとても役に立ちます。

• アーキテクチャー上重要でかならず従わなければならない原則について、デベロッパーと話すための手段として。
• デベロッパーたちがアーキテクチャーの背後のロジックに疑問を持ったときに、チームをまとめるために、あるいは反乱を抑えるために。また、厳しくチェックして、決定に不備があることがわかったときに、反論を受け入れるために。
• 開発中のソフトウェアがそのように設計されている理由(たとえば、なぜ 高価なハードウェア、ソフトウェア部品が必要かなど)をマネージャーなどの利害関係者に説明するために。
• 新しいアーキテクトにプロジェクトを渡すときに(プロジェクトを受け継 いだときに、デザイナーがなぜそのような決定をしたのかがわからないと 思ったことはありませんか？)。

しかし、この実践から得られるもっとも重要なメリットは、次のようなことです。

• 決定の基礎がしっかりしているかどうかを確かめるために、かならず理由 を示さなければならなくなります(次の「53 暗黙の仮定、特に自分自身 のものを疑え」を参照）。

• 決定に影響を与えた条件が変わったときに、決定を見直すための出発点と して活用できます。

• このドキュメントを作るために必要な労力は、会議や議論でメモを書き出すためにかかる労力と同じです。どの形式を選ぶにしても、このタイプのドキュメントは実行してみる価値があるはずです。