Design It! ―プログラマーのためのアーキテクティング入門

11章アーキテクチャを記述する

ソフトウェアアーキテクチャの文書化は、悪名高いことで有名だ。コードを書く時間を奪うし、賞味期限が切れていることがほとんどだ。独自のバイナリファイル形式で書かれていて、手軽に編集できないことも多い。それに加え、それを読む人がほとんどいない！　ソフトウェアアーキテクチャ記述（Software Architecture Description）のことをSADと呼ぶ人がいるのも不思議ではない。

酷いアーキテクチャ記述は私たちを悲しく（sad）させる。しかし、優れたアーキテクチャ記述はチームに明確なビジョンを与える。優れたアーキテクチャ記述は、計画のための資産であり、コミュニケーションを支えるものであり、協働ツールだ。設計判断をすべての人に届ける役に立ち、それによって作り上げるソフトウェアの品質を向上させるものだ。

この章では、人々に愛されるような、素晴らしいソフトウェアアーキテクチャ記述を作成する方法を学んでいく。なぜ人々がそれを愛すのかって？　それは、聴衆が必要とする正確な情報を、人間味がある習得しやすいフォーマットで届けるからだ。愛はソフトウェアアーキテクチャ記述にあてはまる言葉だ。おおげさかもしれないが、私は真剣だ。素晴らしいソフトウェアアーキテクチャ記述を作成することは、あなたが想像するよりもずっと簡単だ。

11.1　全体像を語る

「8.3　コード内にモデルを構築する」で、アーキテクチャのモデルと私たちが記述するコードの間には常にずれがあることを学んだ。モデルとコードのずれは、ある程度は埋められる。しかし、すべてのアーキテクチャ上の設計判断をコードで表現できるわけではない。計画的な設計が最も必要とされる初期の段階には、コードを読めるステークホルダーがほとんどいないこと、そしてコードも存在しないことを忘れないようにしよう。 ...