ソフトウェアアーキテクチャ その12 - ドキュメントを書く上での6つのテクニック [arch]
前回 に引き続き，ドキュメンテーションについて．
前回は「健全なドキュメントを書く7つのルール」を紹介したが，今回は「ドキュメントを書く上での6つのテクニック」を紹介したいと思う．
本シリーズでアーキテクチャドキュメントを扱うのは，今回で最後の予定．
Reference:
Documenting Software Architectures: Views and Beyond,
by Clements, et al. Addison-Wesley 2003
--> Chapter 9, Chapter 11.1 - 11.3
本書には，Appendix に ECS Software のアーキテクチャ仕様書がそのまま例として載っており，私もアーキテクチャ仕様書を記述する際に大いに参考にしている．
但し，本書には関わっている著者が多く，全体的に若干繁雑な内容になっていることは否めない．最初から最後まで読了するというよりは，必要に応じて適切な内容を参照するカタログ代わりに利用すると良いかもしれない．
こちらがその和訳本．
多くの技術書がそうであるように，この和訳書も日本語が非常に奇怪だ．特に本書はその傾向が顕著で，例えば linked list (リンクリスト) が「結合した一覧表」などと訳されている．特に本書に関しては，極力オリジナルを読まれることを強くお勧めする．
Technique 1: Context Diagrams
(コンテキストを明確にする)
システムやサブシステムを表現するにあたり，何がそこに含まれ，何が含まれないかを読み手に把握させることが重要である．
コンテキストダイアグラムを供給することにより，「システムが相互作用する環境」「外部インターフェース」「対象システムが依存する他のシステム」を明確する．
View によって明確にしたい対象は様々だろう．例えば Layered view (Module viewtype) ならシステムと階層構造，Shared data view (C&C viewtype) なら外部要素とのインタラクションパス，Deployment view (Allocation viewtype) なら同じリソースを共有している他システム，など．
Technique 2: Combining Multiple Views
(複数の view を合成する)
これまで，構造を複数の view に分割し，視点を統一させることが重要だと述べてきたが，こうすることで全体像が掴みにくくなり，構成要素間の関係が捉えにくくなることがあるので，ドキュメントではそこをフォローしておきたい．
複数の view を合成するには，2つの方法がある．1つは combined view (合成 view) を構築するやり方．これには "overlay" と呼ばれる view を重ね合わせる方法と，"hybrid" と呼ばれる複数の view の構成要素を結びつける方法がある．もう1つはそれぞれの view の要素と関係同士を説明する bridging document (ブリッジドキュメント) を記述するやり方．
注意したいのは，combined view を用いて view を合成することは，ドキュメンテーションの上では全体像の把握や view 間の関連性の理解に繋がるが，やはり設計プロセスにおいては1つの視点から問題を分離し，複雑度を軽減させて pattern や tactics を検討することが本質であるということだ．
Technique 3: Using Hierarchy
(階層構造を使用する)
読み手にとっても書き手にとっても管理・理解しやすくする為に，アーキテクチャの説明に階層構造を取る．
具体的には，まずはトップレベルの view を記述し，詳細は別の view を用いて説明する．
Technique 4: Documenting Interfaces and Behavior
(インターフェースとその挙動を記述する)
当たり前のことに聞こえるかもしれないが，インターフェースは2つの独立した要素がどのように相互作用するかの境界であり，コミュニケーションの手段である．
つまりこれを明確にするということは，その要素の特性を，外部に対してどこまで意識させるかという宣言になり，それを意識してインターフェース定義を行う．
Technique 5: Notations
(様々な表記方法)
世の中には UML や ADL (Architecture Description Languages) など，既に定義された表記方法があり，それらを使うメリットも多い．
例えば「view を表現する多彩な記述方法を備えていること」「標準化されており，共通言語として利用価値が高いこと」「関連ツールが充実していること」などがメリットとして挙げられる．
但し，同時にそれらのデメリットも意識しておく必要がある．例えば UML は C&C の様々なコネクタやポートを完全に表現できない点 (UML 2.0 でいくつか定義はされたが)，より実装に近いことを表現してしまう点などである．
本書第11章には，UML を始めとする様々な表記方法と，これまで解説してきた view との対応が説明されているので，参考にされると良いだろう．
Technique 6: Choosing the Views
(View を選択する)
最後に一番重要なテクニック．
それは「読み手に適した view と粒度を選択する」ということだ．オーディエンスを意識した内容に仕上げることは，プレゼンテーションでもドキュメンテーションでも同じことである．
本書第9章では，マネージャー，開発担当者，テスター・インテグレーター，他システムの開発者，メインテナー，プロダクトラインアプリケーション担当者，顧客，ユーザー，アナリスト，インフラ担当，新規利害関係者，将来のアーキテクトなど，実に様々な想定読者に対して，それぞれ何をどれぐらい記述するべきかが解説されている．非常に参考になるので，ぜひ一読されることをお勧めする．
0 コメント:
コメントを投稿