やったこと

• Design It! 11章 アーキテクチャを記述する 読了

学んだこと

ポイント

• アーキテクチャ記述の種類
• 優れたアーキテクチャ記述を作成するためにできること
• 設計根拠を残す効果

学び

• アーキテクチャ記述には、いくつか種類がある
  • 部族的な方法
  • 共通の方法
  • 形式的な方法
  • 無駄な方法
• 優れたアーキテクチャ記述を作成するためには、以下が重要
  • 聴衆のことを考えて作成する
  • ステークホルダーの関心事に合わせて、ビューを構成する
  • 設計根拠を残す
• 設計根拠を残すことで、読み手に設計判断の意図を伝えることが出来る
  • 読み手には、アーキテクチャや設計判断の判断残量として機能する
  • これにより、アーキテクチャや設計の一貫性を保ちやすくなる

所感

「アーキテクチャ記述にスライドを使用するな」という話について
あえて機能の制限されたツールを使用することは、表現したい本質から意識がそれることを防ぐ効果があることを理解した。

• スライド作成ツールを使用すると、きれいな作図に意識を取られる可能性が生まれる

メモ

優れたアーキテクチャ記述は、チームに明確なビジョンを与える。
設計判断をすべてのステークホルダーに届け、品質向上に寄与する。

この章では、素晴らしいアーキテクチャ記述を作成する方法を学ぶ。

全体像を語る

アーキテクチャとコードの間には、常に何らかのずれがある。

コードでは、全アーキテクチャ上の設計判断を表現することはできない。
特に、計画的な設計が必要なプロジェクト初期では、コードもないため、アーキテクチャを評価できない。
このようなときに、アーキテクチャ記述は重宝する。

アーキテクチャ記述は、以下の効果がある。

• 整理する
  • 技術同士、または技術と人々がどう連携するのか整理し、記述する
• 技術サイドとビジネスサイドの間で使用できる、共通の語彙を確立する
• 品質特性にスポットライトを当てる
• 考えを明確にする
  • 記述する過程で、頭の中の考えを整理できる
  • わかっていること、わかったつもりになっていること、わからないことを明確にできる
• 評価できるものを作る
• 見せびらかす
  • 優れたアーキテクチャ記述は、顧客や管理職を安心させる
  • チームメンバーに対しても、リーダーシップを発揮する

状況に応じた記述方法を選ぶ

アーキテクチャ記述には、複数の記述方法が存在する。
費用対効果を高めるためには、現在のプロジェクトとチームの状況に応じて、適切な記述方法を選択する必要がある。

記述方法	概説	適した状況	例
部族的な方法	チーム内での認識合わせに重きを置いた、チーム内でのみ通用するような記述。<br>変更は容易だが、チーム外に対して共有するのは困難。	アーキテクチャが固まっていない、プロジェクト初期など	ラフスケッチ、ストーリーテリングなど
共通の方法	チーム外の人々にも共有できる、共通の記述。<br>変更容易な状態を保ちつつ、部族的な方法よりも共有容易な運用が求められる。	アーキテクチャが成熟し、変更する頻度が低下してきた段階	アーキテクチャ俳句、コーディングスタイル<br>アーキテクチャデシジョンレコードなど
形式的な方法	リスクの高いシステムや、高度な調整を必要とするプロジェクトで必要となる、<br>より高い精度や精密さを必要とする記述。<br>膨大な量になる傾向があり、多くの時間と労力を要する。	リスクの高いシステムや、高度な調整を必要とするプロジェクト	SAD(Software Architecture Description)
無駄な方法	変更困難で共有も難しい記述方法。<br>本質以外のことに意識がそれる可能性も	無し	スライドで作成するアーキテクチャ記述

SAD（Software Architecture Descriptionには、様々なテンプレートが存在する。
有名なSADたちは、いずれも以下の基本部分を含む。

• 導入と事前情報
• SADの概要と照会
• ステークホルダー、ビジネス目標、アーキテクチャ上重要な要求の概要
• コンテキストビュー
• 関連ビュー
  • 一つのビューでは、伝えたいこと全てを書ききることは不可能
  • 品質特性やそれ以外の要求を満たす方法について、関連するビューを作成して説明する
• リスク、未解決の質問、今後の課題
• 付録

優れたアーキテクチャ記述を作成する

優れたアーキテクチャ記述は、以下4つの特徴を持つ。

1. 聴衆を念頭に置いて特別に作られている
2. アーキテクチャの複数のビューを示している
3. 要素とその責務を明確に定義している
4. 設計判断についての根拠を説明している

言い換えると、これら4つの特徴を意識することで、優れたアーキテクチャ記述を作成できる。

これらを守ることは、後述する「時間を無駄にするのを避ける」ことにもつながる。

時間を無駄にするのを避ける

変更困難で共有も難しいアーキテクチャ記述も存在する。
その最たる例が、「スライドによるアーキテクチャ記述」である。

• 共有が難しい : 誰かがプレゼンしなければ、スライドは意味を成さない
• 変更が困難 : 整えた見栄えを変更するのをためらってしまう

聴衆に配慮する

聴衆のことを理解できれば、彼らが必要としているアーキテクチャ記述を作成できる。
聴衆が価値を置くものを考える。

• どのような情報を処理するのを好むか
• 渡した情報をどう使うか
• など

理解しやすさに専念する

大事なのは、聴衆とのコミュニケーション。

• 聴衆にとってなじみ深いドメインの言葉を使用、アーキテクチャ記述を作成すると良い
• 平易な話し方を心掛け、専門用語を避ける
• 背景知識が必要なことを示すために、アーキテクチャの概念を簡単に定義する
• など

以下、アーキテクチャ記述で気を付けるべきこと。

すべきこと	避けるべきこと
新しいアーキテクチャあゐ年は、初出のタイミングで定義する	不必要に新しい概念を導入する
ドメイン領域の言語を話す	全員が図の表記法を理解していえると思い込む
図に凡例を含める	専門用語を使う
共通のテンプレートが存在する場合はそれを使用する

ステークホルダーの関心事を中心にビューを構成する

ステークホルダーに合わせて、アーキテクチャやそれに伴う様々な設計ドキュメントのビューを構成する。

• 開発者は、コードの構成、デプロイ、コンポーネントの相互作用などを知りたがる
• テスターは、I/Fや通信プロトコルを知りたがる
• プロダクトオーナーは、技術的な依存関係や全体の進捗を知りたがる
• など

そのためには、「ステークホルダーが何を知りたがるか？」を考える必要がある。

また、アーキテクチャ記述には、少なくとも以下を加えるべき。

• 設計判断とその根拠
• 設計したものの構造

アーキテクチャの文書化方法を決定する際は、必ず聴衆を考慮する。

ビューポイントを確立する

「ステークホルダーの特定の関心事に関連するまとまり」に従って、アーキテクチャを説明する方法を定義するもの。

どんなビューか、誰向けのビューか、ビューの表記法や語彙、規則を定義する。

例えば、コンポーネントの配置先を知りたいステークホルダー向けには、以下のようなビューになる。

コンポーネント	デプロイ先
Web UI	ユーザーのブラウザで実行される
...	...

カスタムビューポイントを作成する

ステークホルダーの特定のニーズを満たすために、カスタムしたビューポイントを構成できる。
特に、品質特定を中心としたビューポイントを構成することは多い。

• スケーラビリティ、セキュリティ、保守性のビューポイント
  • アーキテクチャが特定の品質特性シナリオをどのように満たすか示す
• 規制のビューポイント
  • 規制要求に関心を持つ特定のステークホルダーグループに監査を実施するために必要な情報を提供する
• 学習容易性のビューポイント あるいは チーム受け入れのビューポイント
  • 新しいチームメンバーが、スムーズに開発へ参加できることを目標とした、開発プラクティスを確認できるようにする
• ビジネスインパクトのビューポイント
  • アーキテクチャの各部分がビジネス価値にどのように貢献しているか示す

ビューポイントは、伝統的なアーキテクチャ記述では必須。
部族や共通のアプローチでも、効果はある。

ビューは、アーキテクチャを効果的に共有できるようアイデアを構成するのに役立つ。

判断の論理的根拠を説明する

設計根拠とは、各設計を決定した理由を説明するもの。

品質特性のトレードオフ、コスト、チームメンバーの能力や外的要因など、様々な要因をもとに設計判断を行うはず。
その判断を行った背景を記載すること。

設計根拠を残すことで、読み手は設計の意図を理解できる。
理解した意図から、アーキテクチャの一貫性に寄与する可能性が高まる。

選ばなかった道を説明する

様々な候補の内、選択されなかった設計判断とその理由を残す。
背景知識は、読み手がアーキテクチャやコードを正確に理解することを助ける。