エンジニアは日々現場で学ぶ
開発現場で学べること
第4回　最良のシステム設計書とは？

クロノス 山野寛
2004/1/28

エンジニアにとって最も大切なことの1つが、開発現場での経験だ。それがエンジニアに多くの知識と勘をもたらす。そんな開発現場で若きエンジニアが失敗し、そこで何を学んでいくか。それを毎回紹介したい。

■要求定義から開発フェイズへ移行

　前回（「第3回　システム開発の真の目的を見失わない 」）までわれわれの開発チームは、ある某サービス業を営む企業Aの要求定義をまとめる作業を行ってきた。その作業も3カ月間でようやく無事に終了し、いよいよ本格的な開発フェイズへと移行した。

　開発フェイズではまず初めに、設計手段の統一化を図るため、メンバー全員で設計書の標準化を行うミーティングを実施した。われわれはこのミーティングで、クラス間の静的な関連の記述にはクラス図を、また動的な関連の記述にはシーケンス図を用い、オブジェクトとデータベースへのマッピングやそのほかUMLだけでは表現し切れない部分に関しては、個別に日本語の仕様書を用いるということを決定した。

　少し余談になるが、今回われわれが開発のプロセスとして取り入れているRUP（ラショナル統一プロセス）では、設計内容を視覚的に表現する「ビジュアルモデリング」を推奨している。過去多くの現場を経験した方にはお分かりいただけるだろうが、日本語で記述された設計書の場合、読む側の感性によっては本来とは異なった意味に受け取られてしまうという危険性があり、設計者の意図したものとは違うプログラムが完成してしまうことも少なくない。しかし、UMLのようにビジュアルで記述された設計書であれば、プログラマとのコミュニケーションも日本語の仕様書に比べてはるかに容易である。

　しかし残念なことに、UMLを用いたビジュアル的な設計書を用いることが最良であるといい切れない要因もいくつかある。

　1つ目の要因としては、すべてのエンジニアがUMLを完全に習得しているとは限らない点が挙げられる。UMLの勉強はしているものの、実務で経験したことがない人や、UML導入に対する目的や効果を理解していないエンジニアもまだまだ多く、UMLで設計書を記述することが定着している現場がいまだに少ないという現実がある。

　2つ目の要因としては、日本語の仕様書より設計書の記述に対する工数がかかってしまうという点が挙げられる。紙に鉛筆で書くような場合には日本語で描くより図を用いて書く方が楽だが、パソコンで作業を行う場合は図で記述するよりも日本語をタイプする方が断然早い。またUMLツールによっては修正するのが意外に大変なことも多く、工数の面でリスクを伴ってしまうこともあるようだ。

　さて、話を元に戻すが、この標準化ミーティングで、設計書のテンプレートを私が作成することになった。私がいままで経験してきたほとんどの現場では、あらかじめ標準化された設計書のテンプレートが初めから用意されており、特に何も意識することなくその設計書に記述していたのだが、今回はどのような記述方法がベストなのかを試行錯誤しながら設計することになったのである。

■製造の過程において

　私が設計書の記述方法に関して最も頭を悩ませたのは、今回のシステムの中で最も複雑で難易度の高いプログラムの設計を行ったときである。このプログラムでは、会計処理に関する計算をメインとする非常に複雑で難解なロジックを作成する必要があった。そこで私は、仕様をプログラマへ漏れなく伝えることを意識し、ステップレベルまで詳細化したアクティビティ図を補足資料として用いることにした。こうすることによって、さらにプログラムの精度が上がると予想したためである。

　しかし私の思惑に反して、プログラマから次のような反応が返ってきた。

プログラマ　「設計書が細かすぎて分かりにくかったです。日本語の仕様書が欲しかったですね……」

　確かに、必要以上に詳細なアクティビティ図を記述してしまったため、かえってプログラマを混乱させてしまったようだ。いったい何の処理を行うためのコードを記述しているのか、プログラマは見失ってしまったらしい。「多分こういう仕様だろう」という想像で記述した部分から、後になって多くのバグが発生した。さらに単体テストでの効率低下も重なって、予定工数を大幅にオーバーしてしまった。

　私はこのエピソードをきっかけに、常に「最良の設計書とは」を考えるようになった。

■設計書の目的とは

　ここで設計書の目的についていま一度確認したいと思う。筆者は、「設計書は、設計者が製造者に対してプログラムの製造を依頼するためのコミュニケーションのツール」であると考えている。つまり、設計書を記述することの目的は、設計者が考えているプログラムの仕様を漏れなく製造者に伝えることに尽きるのである。例えば設計書の精度が非常に高く、設計者の要求どおりのプログラムが完成するのであれば、それだけ製造の際のバグも減り、全体としての工数削減となるのは容易に想像がつくだろう。逆に設計書があいまいに記述されていれば、どれくらいのリスクを伴うのだろうか。

　一般的に、設計段階でバグが発見された場合と製造段階で発見された場合の手戻りのコストは、以下の図1のようになるといわれている。

図1　設計段階と製造段階でバグが発見された場合の手戻りコストの違い

　設計段階で見つかったバグに対する修正は、設計書の修正だけで済むが、製造（単体テスト）段階で発見されたバグはプログラムの修正と設計書の修正が必要となり、その手戻りコストは数倍にも及ぶ。それだけ設計書の正確さは重要である。

　現場によってはスケジュールの都合上、製造後に設計書を納品のためだけに記述するようなこともしばしば見受けられるが、これでは本来の設計書の目的とはかけ離れた無駄なドキュメントにしかならない。当然のことながらそういった現場で作られたシステムほど製品としての品質は低いようである。

■設計者が意識しなければならないこと

　では、設計書をコミュニケーションの道具であると考えて記述する場合、設計者が最も考えなければならないことは何だろうか。筆者は上記で述べたようなエピソードがあって以来、設計する場合に最も気を使っていることがある。それは、

　「○○○はこの設計書を見ただけでプログラムを作れるか」

ということである。読者の方にも考えていただきたいという理由で、この文章には主語（○○○の部分）を入れていないのだが、あなたはここに何が入ると予想しただろうか？「私」や「プログラマ」と考えた人もいるだろう。が、私は、

　「Aさんはこの設計書を見ただけでプログラムを作れるか」

ということを念頭に置くことにしている。つまり、この設計書を見てコーディングを行うのは「私」でも「プログラマ」でもなく「Aさん」だという具体的な事実を常に考えて設計するべきだということだ。

　もしもこのプログラムを作るのが設計者の「私」だとすれば、おそらく独り善がりの設計書になってしまうだろう。つまり自分のスキルや知識を基準として作成された設計書は、他人から見れば非常に理解しがたい設計書となってしまう可能性を秘めているということである。先ほどのエピソードはまさに、「私がプログラマならこうコーディングする」と考えて記述してしまった結果だといえる。

　また、「プログラマ」という抽象的な人物を対象として設計書を記述した場合はどうだろう。おそらく、誰でもプログラムが書けるような全網羅的な記述が必要となり、設計書の記述に無駄な時間を費やしてしまうこととなる。近年、設計書や仕様書といった開発の中で生産されるドキュメントの肥大化が問題視されており、「余分な設計書を作ることに労力を費やすことは無駄」であるとの認識が一般化されつつある。

　われわれエンジニアの使命は、「システムを作る」ことであり「設計書を書く」ことではない。開発コストの削減や納期の短縮傾向にあるいま、いかにドキュメントに費やす工数を削減するかが重要であることを考慮すれば、万人を対象とした設計書を記述することにはやはり無駄が多いだろう。

　上記を基に私が出した1つの結論は、そのプログラムを製造する技術者のスキルを設計者が理解し、その人に合った設計書を記述することが設計を作るうえでの重要なポイントであるということである。しかしこれは設計書がコミュニケーションツールであるという意味以上に奥が深く、かつ難しい部分であるように感じているのも確かだ。そもそも、設計者が製造にかかわるプログラマのスキルをきちんと把握できる環境が常に用意されているとは限らないのである。

■設計書の詳細度に伴うリスクとは

　設計書を作成する場合、上記のようにプログラマのスキルを考慮するということ以外に、設計記述の詳細さによって伴うリスクについても踏まえておく必要がある。まず、設計書には必要事項だけを記述し、そのほかの部分に関しては口頭だけの説明で行い、実装の多くを製造者が判断するとどのようなリスクが発生するのか？ この場合は以下のようなものが考えられるだろう。

（1）製造者の仕様理解不足によるバグの発生
（2）設計書に載らないバグの増加
（3）クラス（モジュール）の再利用性低下

　特に注意が必要なのは（2）の「設計書に載らないバグの増加」である。製造者判断によってコーディングされた結果生み出された「設計書に載っていないバグ」を排除するためには、その個所の特定を行うためのトレース方法が貧弱であるため非常に工数がかかるからだ。

　口頭で仕様の説明を行った場合、上記のようなリスクは必ず存在する。しかし、現場の環境やスケジュールの都合によってはそうせざるを得ない場合もあるだろう。もしそうした場合に多くのバグが発生したとしても、われわれ設計者はこの原因を決してプログラマのせいにしてはならない。それはプログラムのバグでもプログラマのミスでもなく、設計書のバグであり、設計者のミスなのだから。

　逆に、口頭での説明が不要なくらい詳細な設計書を書いた場合はどうだろう。もちろんそうした場合も以下のようなリスクが考えられる。

（1）設計者の負担増加
（2）製造者の仕様不理解によるプログラムおよび単体テストの精度低下

　（1）に関しては、テストファーストなどで設計者が単体テストケースの記述を行うことを義務付けた現場では非常に顕著であり、設計者とプログラマのチーム編成やスキル次第では設計が追い付かなくなる可能性も高い。（2）は先ほどのエピソードで述べたように、あまりに詳細な設計書があることによって、プログラマ自身が仕様を理解しようとする努力を怠り、安直な判断によるコーディングを行ってしまう可能性があるということだ。

■最良の設計書とは

　こうして考えると、どんな設計方法や記述のレベルで行っていてもそれぞれにリスクが発生するようだ。しかし、われわれ設計者はこれらの事柄を踏まえたうえで、最良と思われる設計手段を模索しながらプロジェクトを進めていくことが必要である。ひょっとしたら、いま、あなたが記述している設計書に対して、プログラマは大きな不満を持っているかもしれない。

　私はこの場を借りて設計を行っている皆さんに尋ねたい。

　「あなたが思う最良の設計書とは何ですか？」

筆者プロフィール

山野寛（やまのひろし）●クロノスに勤務するシステム・アーキテクト。立命館大学理工学部 卒業。クライアント／サーバからWeb系システムを中心にいくつかの開発現場に参加し、ここ数年はJ2EEをメインとしたオブジェクト指向開発にアーキテクトとして設計から携わっているという。