特別公開！アーキテクチャドキュメント

株式会社オージス総研
オブジェクトテクノロジー・ソリューション部
平澤　章

・はじめに

・システムの概要

・そもそもアーキテクチャとは？

・アーキテクチャドキュメントを書こうとしたら

・アーキテクチャドキュメントを特別公開！

・アーキテクチャドキュメントは必要か？

・謝辞

・関連リンク

はじめに

この記事では、以前私たちが実際に関わった開発案件で作成した「アーキテクチャドキュメント」を公開します。

別に国宝のお寺の庭に入れるわけでもないのに、「特別公開！」などという表現はずいぶん仰々しいな、と思われる方もいらっしゃるかもしれません。しかし特定のお客様向けに作成し納品したドキュメントを、そのまま外部に公開してしまうような例を、私自身はあまり聞いたことがありません。
これって結構特別だと思うのですが、手前味噌でしょうか？

システムの概要

ご紹介する開発案件の名称は「新石炭総合ＯＡシステム」といいます。これは、宇部興産株式会社殿で使われる社内システムで、在庫管理、販売管理などの機能を提供する典型的なビジネスアプリケーションです。
開発主体は株式会社宇部情報システム殿です。弊社（オージス総研）は、プロジェクトの立ち上げ期間の約３ヶ月間、２名が参加し、概念モデリングのコンサルティングと、アーキテクチャ設計および実装作業を行いました。

システムは Microsoft の IIS / ASP を利用した、WWW ベースのイントラネットシステムです。DB エンジンには Oracle8を、開発言語には Visual Basic （以降 VB ）と VBScript を採用しました。

このシステムの大きな特徴は、なんと言ってもサーバーを VB で開発したことでしょう。ちょうどサーバー対応機能が強化された VB 6.0 が発売されて間もないタイミングだったのですが、実際に VB を使ってサーバーを開発した事例はほとんどなかったため、多くのことを手探りで調べる必要がありました。これは技術的には大変面白かったものの、短期間で仕事を完結させなければならないプレッシャーもあり、私たちにとっては非常に密度の濃い仕事でした。

このプロジェクトで私たちが行ったアーキテクチャ設計・実装作業は、具体的には次のようなことでした。

そもそもアーキテクチャとは？

アーキテクチャという言葉は、以前から講演や書籍などで聞いたり、見かけたりする機会がよくありました。しかし私自身は正直なところ、アーキテクチャが具体的に何を指すのか、当時よく理解できていませんでした。「アーキテクチャとは何か？」をズバリと一言で理解したかったのですが、その答えはどこにも見つからなかったのです。

Booch 氏の定義

２年前にUMLの開発者、いわゆるスリーアミーゴの一人でもある Grady Booch 氏が来日しました。当時 Booch 氏は、アーキテクチャに強い関心があったようで、ワークショップや講演でもアーキテクチャについて語る機会が多く、次のような定義を披露していました。

いかがでしょう？
結局、私にはなんだかよくわかりませんでした。これを聞いたとき、言っている内容がよくわからず、途方に暮れてしまったことを思い出します。

4+1 ビュー

さて、次はRational 社の提唱する開発プロセスである「ラショナル統一プロセス」（Rational Unified Process、以降 RUP ）です。

RUPにおいても、アーキテクチャは非常に重要なコンセプトで、4+1 ビューという考え方が紹介されています。これは、「アーキテクチャは論理ビュー、プロセス（並行性）ビュー、実装ビュー、配置ビューの４つに、ユースケースビューを加えた５つの視点（ビュー）で定義される」というものです。

私はこれを、アーキテクチャは５つの見方で表現できること、あるいはアーキテクチャ構築の成果物には５種類のものがあること、と理解しました。しかし「アーキテクチャとは何か？」という基本的な疑問は依然として解決されませんでした。
またそもそも外部仕様を表現するユースケースが、アーキテクチャの中心というのもずいぶんおかしな話に思えたものでした。

結局アーキテクチャとは

ということで、私にとっては長い間、「アーキテクチャ」は「ソフトウェア開発では非常に大切なものだがその実体はよくわからない」という定義でした。

しかし、このプロジェクトの経験などを通じて、今ではアーキテクチャの定義についてかなり明確に整理することができた、と自分では思っています。参考までに私の解釈を以下に書いておきます。
私の解釈は、「アーキテクチャ構築作業は、大きく次の４つに分割することができる。そして、アーキテクチャという言葉は、局面によって以下の４つの結果のどれかを指していたり、あるいはまとめて全部を指していたりすることがある。」というものです。

上記のように考えたら、非常にすっきりしました。こんなに違うことをまとめて「アーキテクチャ」と呼んでいるのだとしたら、わからないのも当然ですね。（もっとも「アーキテクチャが大切だ！」などといって、人を煙に巻くのにはとても便利な言葉なのですが。）

アーキテクチャドキュメントを書こうとしたら

さて、 RUP ではたんにアーキテクチャの重要性が強調されているだけでなく、アーキテクチャを構築する際の考え方や作業手順に加えて、成果物の標準的な形式も定義されています。これは具体的にはアーキテクチャドキュメント (Architecture Description Document) というもので、親切なことに Word のテンプレートまで用意されています。

アーキテクチャ構築の考え方や作業手順は一般的に書かれているため、自分が担当するプロジェクトで必ずしも直接役に立つとは限りません。むしろ何かに迷ったときのヒント集ぐらいに軽く考えるとよいでしょう。（少なくとも私はそうしています。）

しかし、成果物の形式については、自分でゼロから章立てを考えるよりも、あらかじめ用意されているものを利用した方が楽です。そこで RUP で用意されている Word テンプレートに従って作ってみることにしました。

先ほど書いたようにRUP ではアーキテクチャは 4+1 ビューにより表現されるという立場のため、アーキテクチャドキュメントの章立てもこの順序に従っています。つまり、前書きの後は、「ユースケースビュー」→「論理ビュー」→「プロセスビュー（並行性ビュー）」→「配置ビュー」→「実装ビュー」という順番になっています。（注：RUP の最新バージョンでは若干変更されているようです。）最初はこれでも良さそうに思えたのですが、いざそれに沿って書こうとすると、いろいろとやりづらい点を感じました。思いつく限り挙げてみましょう。

1) ユースケースビューに何を書くか？

最初に悩んだのが、ユースケースビューとして何を書くべきかです。単純に考えればユースケース図やユースケース一覧表、あるいはユースケース記述をすべて集めたものをまとめればいいことになりそうです。しかしユースケース記述を全部集めたのではドキュメントのボリュームが大きくなり過ぎますし、そもそも外部仕様を網羅的に記述するのはアーキテクチャドキュメントとしてふさわしくないと感じました。

そこでアーキテクチャドキュメントには、アーキテクチャを構築する上でどのユースケースを選択したか、そしてその理由はなぜか、について記述することにしました。

2) 論理ビューが先か、配置ビューが先か？

ユースケースビューの次は論理ビューです。一般的には論理ビューに書く内容は、パッケージ構成や中心的なクラスの説明になりますが、最初にこれを書いて、その後から配置ビューを書く順序にも違和感を覚えました。なぜかというと、このシステムでは論理ビュー（＝ソフトウェアの論理構造）を設計する前に、配置ビュー（＝ハードウェアや基本ソフトウェアの選定）がすでに決まっていたからです。（もっともほとんどの場合、インフラの選定をしてからソフトウェアの設計に着手するのが一般的でしょう。）

そこで、最初に「システム構成」という章を設けて、配置ビュー、すなわちハードウェアや基本ソフトウェアの構成について簡単に説明してから、残りのビューの説明を記述することにしました。

3) 論理ビューと実装ビューの違い？

このシステムでは、開発言語に VB を採用しました。ご存じの方もおられるかと思いますが、 VB 6.0 では、実装の継承機能がサポートされていません。（スーパークラスで属性やメソッドを記述しても、サブクラスにはインタフェースだけしか継承されません。）私たちは、当時 VB 6.0 を使った設計に慣れていなかったため、次のような順番で作業をしました。

私は「論理ビュー」という言葉を「実装技術に依存しないソフトウェア構造」と解釈しました。単純に考えれば、上記の 1. を論理ビューに書き、 2. を実装ビューに書けばよいことになります。しかし実装ビューにはさらに、プロジェクトファイルの分割運用方法や、Instancing プロパティの設定基準など、VB 固有の情報について書きたいことがあったため、論理ビューと実装ビューそれぞれに対して、何をどこまで書けばよいのか少々悩んでしまいました。

結局、VB 6.0 に依存しないソフトウェア構造の説明から始めると全体が冗長になってしまうことから、論理ビューでは VB 6.0 の制約事項を前提としたソフトウェア構造を記述することにしました。

アーキテクチャドキュメントを特別公開！

さて、前置きがずいぶんと長くなりましたが、ここがこの記事の本題です。

なおタイトルですが、「アーキテクチャドキュメント」という名称は馴染みづらいと考え、「アーキテクチャ設計書」としました。

アーキテクチャドキュメントは必要か？

さて、最後にアーキテクチャドキュメントの必要性について少しだけ議論してみたいと思います。

最近の XP (eXtreme Programming) ムーブメントでは悪者扱いされることも多いようですが、こうした手書きのドキュメントは果たして本当に必要ないものなのでしょうか？

たしかにこうしたドキュメントを作ってしまうとメンテナンス負荷は増大します。誰しもコードとドキュメントの二重管理、あるいは UML モデルも含めて三重管理になるような事態は避けたいことでしょう。

しかし一方で、どんなに優れたデザインであったとしても、数万行、数十万行もあるようなコードや、数百クラスも書かれているような UMLモデルから、中心となるソフトウェア構造や、重要な設計判断を理解するのは容易ではありません。特にプロジェクトに後から参加するメンバーにとっては大変なことでしょう。

そこで、後々まで続くプロジェクトならば、必要最小限のドキュメントを作る必要があると思います。ドキュメントを重要視しすぎることは確かに問題でしょう。しかし数ヶ月後には、自分自身でさえ、重要な設計判断をどういう理由で下したのかを忘れてしまうことだってよくあります。（少なくとも私はそうです。）そうした事態を防ぐためには、コード、UML モデルと合わせて、最低限必要なドキュメントを作る必要があると思います。そして、そのドキュメントとは、外部仕様を記述するもの（ユースケースなど）と、この「アーキテクチャドキュメント」ではないでしょうか。

謝辞

このような、実名入りでの資料公開を快くご了解いただいた、株式会社宇部情報システムの野村常務取締役、吉本部長、猪八重課長、山本主査、国安様をはじめとする関係者の方々、および宇部興産株式会社の関係者の方々に、改めて厚く御礼を申し上げます。