川村渇真の「知性の泉」

仕様書:設計内容を記述してレビューや製作に用いる


レビューやソフト作成に仕様書は必要

 システム開発で設計した内容は、仕様書として記述する。設計の段階だけでなく、最初の調査や分析の結果である要求仕様など、いろいろな工程で仕様書を書く。テストに関してなら、テスト内容を記述した「テスト仕様書」や、テストシステムの仕組みや構成を説明する「テストシステム仕様書」などがある。
 仕様書を作成するのは、開発を成功させたいためだ。分析や設計の内容を記述すれば、きちんとしたレビューが可能になる。設計内容を正確に記述しておけば、プログラムやデータなどを正しく作れる。また、後からシステムを変更しなければならないときも、システムの内容を把握したり、直すべき箇所を調べる作業が容易になる。全体としては、システムの有用性、信頼性、柔軟性などを高めるのに役立つ。
 以上のような理由により、開発の各段階で仕様書を書くのは当然といえる。一部には、仕様書を書かずに開発を進める人もいるようだが、あまりにも低レベルすぎて話にならない。ハッキリと言ってしまうが、仕様書を書かないなら開発の仕事から外れてもらいたい。それほど基本的なことであり、やって当たり前の行為なのだ。
 どのような仕様書を作成するかは、プロジェクト管理の中で明確に示す。どの段階で何という仕様書を誰が書くのか、また誰がレビューするのかを、事前に決めて公開する。仕様書の作成期日やレビュー日程まで明らかにするので、作り忘れやレビューし忘れも起こらない。また、担当者を明確にするので、各人が自分でスケジュールを管理し、責任をもって仕事が進められる。仕様書をきちんと作らせるのも、プロジェクト管理の役割である。

システム全体を把握できる仕様書体系に

 仕様書をどのように書くかは、採用したシステム開発方法論や設計技法に大きな影響を受ける。分析段階からオブジェクト指向技術を用いるなら、それに合った記述方法を使わなければならない。記述方法を選ぶ際には、デファクト・スタンダードか、そうなりそうなものを優先する。オブジェクト指向なら、現時点ではUML(Unified Modeling Language)が有力だ。他の記述方法でも、長く使えるものを選ぶ。
 どのような記述方法を採用するにしても、仕様書全体で満たすべき条件がある。それは、記述された内容をきちんと把握できるように書くことだ。システム開発での仕様書は、作業工程に合わせて何種類かを作る。最初の要求仕様から始まり、テスト内容や運用ルールなども含まれる。各工程で設計する内容が、前工程で作られた内容と合っているのか、きちんとレビューできなければならない。前工程で出した各機能が全部盛り込まれているか、書いてない余分な機能が追加されていないか、前工程の記述内容と矛盾していないかなどを検査する必要がある。
 このような検査を容易にするには、仕様書と機能に管理用のIDを付ける方法が有効だ。まず、開発の各工程ごとに仕様書を分け、どの工程に属しているのか分かる形にする。次に、すべての仕様書にユニークなIDを付ける。これにより仕様書のIDは、工程番号と書類番号を合わせたものになる。仕様書に記述する機能にも、同様にユニークなIDを付ける。機能の数が多いので、2〜4階層の分類ルールを決め、分類内で重複しない番号や記号を付ける。この結果、機能のIDは機能分類と識別番号を合わせた形になる。仕様書のIDも含めると、工程番号、書類番号、機能分類、識別番号の4つで機能のIDを表せる。
 以上のような方法なので、1つの機能に関して、各工程ごとにIDが付けられる。書いてある内容は異なり、後の工程ほど機能の内容が細い。前のほうの工程では機能が荒いので、機能分類ルールの最上位レベルしかIDに付けない。工程が後ろに進むほど、機能分類ルールのレベルを増やして付ける。機能分類ルールは、要求仕様から付け始めて全体を統一したいが、要求仕様の段階では内容が抽象的すぎて、適切に分類するのが難しい。実際には、システムの基本構造が確定する概要設計段階に、機能分類ルールを決めるのが適切だ。そのため、要求仕様の段階だけは機能分類ルールを用いず、独自のルールでIDを付ける。
 機能分類ルールとしては、内部構造から見た分類と、対象業務から見た分類の2種類が考えられる。業務から見た機能のほうが重要なので、そちらを採用したほうがよい。もしコンピュータ側にしか関係のない機能がある場合は、それ専用の項目を分類に追加して対処する。
 設計内容のレビューでは、隣り合った工程間で各機能の内容を比べ、設計した内容が正しいか確かめる。工程間の機能を効率的に検査するためには、機能の関連を明らかにする必要がある。関連性は、工程間の機能関連表として、仕様書とは別に作成する。すべての機能にIDが付けてあるので、関連性はIDで表現できる。こうして作った表で関係を参照しながら、レビューを実施する。
 以上のように仕様書を作れば、システム全体で機能が把握しやすく、レビューの質も向上する。それにより、システムの質が高まるのは言うまでもない。

記述方法を標準化して手間を軽減する

 仕様書を細かな点まできちんと書くのには、大変な労力が必要とされる。できるだけ無駄なものは書かないようにしながら、大切な点は細かく書くことが求められる。このバランスは難しく、記述範囲と書き方を適切に決めなければならない。
 仕様書で書くべき範囲だが、もっとも注意すべきなのは、個々のプログラムの仕様だ。内部構造も一緒に書きたがるが、そうすると実際のプログラムと異なる点が出てきて、仕様書を直す羽目になる。そうではなく、外部から見た動きだけを記述するようにしなければならない。それと同時に、プログラムのソースコードは、全体の構造を把握しやすい作り方が求められる。仕様書を標準化するだけでなく、プログラムの作り方も標準化する必要がある。
 エラー処理などは、プログラムごとに同じ内容を書くことが多い。それを防ぐには、共通の仕様書として最初に作成し、それを参照する形で書くのが一番だ。個々のプログラムの仕様書では、どの方法で処理するかを参照するとともに、表示するメッセージのような個別の内容だけを指定する。
 書き方に関しては、仕様書の種類ごとに標準化してテンプレートを用意し、プロジェクトのIDなどを最初から入力しておく。テンプレートを呼び出して、必要な箇所だけ入力する方式なら、作成の手間を軽減するとともに、書式を統一する効果もある。
 どのソフトを使って仕様書を書くのかは、悩むことの多い問題だ。機能にIDを付けて関連も表すので、リンク情報を含められ、素早くジャンプできるものが望ましい。これらの条件を満たすのはHTMLが適している。ただし、作成の手間を軽減する意味から、HTMLのタグをいちいち入力していたのではダメだ。WYSIWYGタイプのウェブページ編集ソフトを用い、リンクまで含めて作るとよいだろう。作成したものを組織内で公開すれば、関係者が誰でも見られるだけでなく、関連する書類へ素早くジャンプできて読みやすい。
 書き方で一番大切のは、機能の説明方法である。条件ごとに異なる処理など、よく使うパターンごとに記述方法を標準化しておく。長い文章だけで説明すると分かりづらいので、箇条書きを広く活用したい。記述方法の標準化では、箇条書きを大いに取り入れるべきだ。
 どのような書き方を採用するにしても、大切なのは論理的で正確に書くこと。この点を一般論として教えるのは難しいので、書き方の良い例と悪い例を何種類か用意し、どんな点が違うのかを説明するとよい。このような方法でも、例の種類を増やすことで、かなりの効果が期待できる。

素早く書けるように訓練すべき

 仕様書の作成では、効率的に素早く作ることと、内容をきちんと書くことの2つが求められる。それを実現するためには、事前の準備が大切となる。
 仕様書を書き慣れていないと、書くのに相当の時間がかかる。突然と書くように言われても、どうしてよいのか戸惑う人は多い。ところが現実には、実際のプロジェクトで初めて書かせる場合がほとんどだ。これでは、分かりづらい内容になるのが当然で、それが仕事の仕様書として残ってしまう。よく考えたら大変なことをしているのだが、それに気付かない人が多すぎる。
 このような失敗を少しでも防止するために、仕様書を書くための訓練を実施する。練習で悪い点を直されれば、本当に書くときには、ある程度のレベルから始められる。訓練では、きちんと書けるようになるだけでなく、素早く書けることも重視する。
 仕様書を書く訓練は、2段階に分けて行う。最初の段階では、論理的で正確な書き方を学ぶ。開発の工程ごとに作成する書類が異なるので、すべての書類で書き方を教えるとともに、実際に書かせてみる。書類の種類ごとに何回か練習すれば、迷わずに書けるようになるはずだ。
 そこまで達したら、次の段階へと進む。時間をかけずに書くことが大切なので、設計しながら書く訓練をする。仕様書の作成にはパソコンを使うが、思い付いたアイデアを最初から入力し、パソコンの書類上で試行錯誤する。これに慣れると、後から仕様書を書く時間を余分に取るようなことはない。  仕様書を素早く書けるようになれば、細かな点まで書いても時間が不足しない。仕様書の質が上がって、質の高いレビューも可能になる。全体として良い方向に進むわけだ。その意味で、仕様書を素早く書く訓練は大切である。

書いた仕様書を見れば実力が推測できる

 多くの開発では、仕様書の書き方や活用方法を十分に考えてない。しかし、システムの質を向上させたり、成功の可能性を高めるためには、仕様書が非常に重要となる。また、仕様書を良くすることは、それを書くシステム設計者の質を上げることでもある。
 面白いことに、仕様書には、書いた人の能力がどうしても出てしまう。設計した内容だけでなく、書き方自体も能力を伝える。論理的に考えるのが得意なら、説明の仕方が論理的になるからだ。また、システム設計が得意なら、仕様書の全体もすっきりと整えて読みやすく仕上げられる。総合的に見て、システム的な思考が得意な人ほど、分かりやすい仕様書が書ける。その意味で仕様書は、実力を判断するためのバロメーターとしても使える。
 システム設計の実力を高めたいなら、いろいろな設計技法をマスターするだけでなく、良い仕様書を書けるように努力すべきだ。そのために最も有効な方法は、仕様書自体をシステム設計することである。仕様書を書く目的から必要な機能を洗い出し、それに適した仕様書体系や書き方を導き出す。そんな視点で仕様書を考えれば、質をかなり向上できるだろう。

(1998年11月30日)


下の飾り