by マーチン・ファウラー(Martin Fowler): November/December 1997 号への寄稿

依頼を請けたオブジェクトモデルのレビューについて、その顧客と話をして いる時だった。「先にドキュメントだけ、お送りした方が便利ですかね？」
こう聞かれて、気乗りはしなかったが、ええ、はい、その方が便利ですね、 と答えておいた。二日後に、郵便局の配達夫が私の自宅のドアの前に小包を落 していった時にはデカイ音がした。優に 1.5インチの幅がある「ドキュメント」 であった。

開いてみたら、何かの CASE ツールからのプリント出力だった。絵がいく つかあって、後は 全てのクラスの全ての属性と全てのオペレーションに関す る徹底した説明書き。その全部に「定義」が付けられている。契約(Contract) クラスは、"複数の参加者の間の契約" として定義されている。その 契約日 (dateSigned)属性は "契約が結ばれた日" として定義されている。
この 1.5 インチの幅を読み切った後も、さして私の理解は増えなかった。そ のオブジェクトが何であるか、ということはたくさん書かれていたが、何を 「する」目的でそこにあるのか、ということについては、ほとんど説明がなかっ たからだ。
こういう目に合うのは初めてじゃないし、これで最後だとも到底思えない。

なぜぼくらはわざわざ、モデリングとかドキュメント化とかするのだろう か？作ったところで実行出来るわけじゃないし、お客はきれいな図に対してで はなく動くコードに対して対価を払うというのに。わざわざモデルを作るのは、 コミュニケーションのためだ。ソースを眺めるよりもオブジェクトモデルで図 示したほうが、オブジェクトがどう協調するのかが明確に理解できるはずだ。 クラス定義ファイルのコールパスを追いかけるよりも、インタラクション図の 方がクラス間の協同をより良く示せるはずだ。 しかるに、設計ドキュメントの類でこの目的の役に立たないものが非常に多く、 私はソファーで独り悩むこととなる。

問題の一部は、みんながドキュメント生成に使っている CASE ツールにあ る(CASE ツールには、ドキュメント化とコード生成との二種類の目的があるが、 ここでは前者だけを考えよう)。CASE ツールはあなたを字引のような性格にし てしまう。全てのクラスに対して項目を立てたり、図の中に全クラスとその全 属性を書き込んだり、全てのユースケースのインタラクション図を書いたりし てしまうのだ。CASE ツールがあると、「ぜんぶドキュメントに書いた？」な んて質問に答えようとして、完全主義をつくり出してしまう。

しかし、この質問は間違った質問なのだ。もし全てをドキュメント化しよ うというなら、全てに等しい重要度を割り当てて扱うことになる。複雑なシス テムに対してそんなことをすれば、細部に埋もれてしまうだろう。どんなシス テムだって、ある面はほかの面よりも重要だってことはあるはずだし、ここさ え理解すればあとの理解が楽になるような、鍵となる部分があるのだ。これら の側面をできる限り明晰に文章化することが、ドキュメントでの腕の見せどこ ろである。こうすれば重要な領域が強調され、詳細はコードにまかせてしまえ るのだ。

結局、ドキュメントは簡潔で無くてはならない。ドキュメントが簡潔であっ てはじめて、みんなも読んで理解してくれるだろう。ドキュメントが簡潔であっ てはじめて、あなたも更新しようという気になるだろう。「全て」について記 述することなど出来ないし、そうすべきでもないのだ。友人の一人があるプロ ジェクトについて語ってくれた。そのプロジェクトでは、コードが長いからで はなくドキュメントが長いから、みんなクラスの名前を変えたがらないという。
文章化が問題になったら、対策を講じるべきだ。ドキュメントのすくなくとも 半分は、捨ててしまおう。

何を書くべきか？

書くべきことを決めるには、どうしたらよいのだろうか。残念ながら、あなた 自身のプロフェッショナルな判断にまかされているとしか言いようがない。よ りどころとなるルールはない。設計者として、また表現者としてのあなたのス キルしかないのだ。みんなが「全て書こう」とするのはこのせいかもしれない。 何を捨てるべきなのか、決められないからだ。というわけで、私が今のところ 使っている方法を紹介しよう。

もしシステムがそれほど大きくないなら、システムを(UML とか Java と かで)パッケージに分割する。各パッケージは、一つの特定の目的のために協調 するクラス群から構成される。
システムの全体構造を、パッケージとパッケージ間の依存関係との図によって ドキュメント化する。(これは UML だと、クラス図の特殊な使い方となるが、 私自身はなんどもこれを使っているので、パッケージ図という名前で呼ぶこと が多い。詳しくは私の UML 本を読んで欲しい。)
設計を見直して、この依存関係が最小になるようにする。これは、システム内 のカップリングを小さくするうえで重要である。(やり方について書かれた本 は少ないが、私の知識ではロバート・マーチン "Designing Object-Oriented C++ Applications Using the Booch Method" が最も優れている。)

各パッケージにたいして簡単なドキュメントを付記する。ここには基本的 に、パッケージが行うことでカギとなるものについて、そしてその実現方法に ついて説明する文章を書く。補助として UML 図を用いてもよい。パッケージ 内の重要なクラス群に関してクラス図を一枚書くが、全部のクラスに付いて書 かなくてもよい。各クラスには重要な属性と操作のみを記述し、全部書くこと はしない。実装よりもインターフェースに注力する。
パッケージ内での重要なコラボレーションに対して、それぞれインタラクショ ン図を描く。もし注意すべきライフサイクルをたどるクラスがあれば、状態図 を描く。ドキュメントはなるべく小さくまとめて、最新状態への更新が面倒で ないようにする。私は普通、12 ページを越えないように気を付けている。

各パッケージごとのドキュメントだけではなく、パッケージ間にまたがる コラボレーションについても記述があると便利である。このために、カギとな るユースケースをシステムから見つけだし、それをインタラクション図と説明 でドキュメント化する。関係するクラスのなかで重要なものを取り出したクラ ス図もあると便利である。
多くの人が、システムで作ったユースケースの全てに対してインタラクション 図を書くべきだと主張している。これはドキュメント化の行きすぎにつながり かねないと思うが、もしそのほうが便利なら、また常に更新する手間が問題に ならないというのなら、全部書くべきである。とは言え「関係者全員が理解し ていなくてはいけない」と指定されるようなカギとなるユースケースの数は、 一ダースを越えないようにしておくべきだ。

なんといってもコミュニケーションである。

この記事全体で私が強調してきたことは、コミュニケーションである。CASE ツール群には批判的なことを述べたが、これもつまりは、ツールを使っている からといってその人がコミュニケーションしているとは限らないのだ、と言い たかったわけだ。どんなツールであれコミュニケーションを促進したり阻害し たりする可能性がある。要は使い方次第だ。

ところで私は、この記事を書き始めるに際して、自分が語れる内容の多さ に圧倒されてしまった。たくさんの逸話やアドバイスが脳裏に浮かんできたの だ。しかし私は、読者にこの記事を読んで内容を憶えてもらうには、そのうち の少ししか触れることが出来ないだろうことをわきまえていた。どうしても触 れなくてはならない重要な一部を選び出す必要があった。それがコミュニケー ションだ。よいコミュニケーションのカギは、重要な部分を強調することだ。全 てを述べ尽くすのはコミュニケーションとは言わない。それは逆に、読者に重 要なところを抜き出す作業を押しつけ、読者を分厚いドキュメントでうんざり させているだけなんだ。情報の選択こそ、コミュニケーションで重要なことの 一つであり、さらに全ての設計者が持つ責任でもあるのだ。