仕様書は設計しながら書くのが必須

設計は書いて整理しながら進めるもの

　ソフトウェアを中心としたシステムの開発では、考慮しなければならない点が非常に多くある。問題領域から見た機能の設計、ソフトウェアとして実現するための内部的な工夫、信頼性や処理効率を向上させるための工夫などだ。他に、問題領域や動作環境に関わる例外状況への対応、操作や運用がしやすい設計など、挙げていけばキリがないほど出てくる。
　こうしたシステムを設計する場合、頭の中で検討するだけでは、質の高い設計内容が得られない。検討項目に漏れがないか、全体や各部の整合性は確保できているかなど、いろいろなことを考える必要があり、それを頭の中だけで整理できないからだ。
　仕方がないので、検討中の内容を書いて整理するしかない。書くと言っても、今の時代は、紙に書く人は少ないだろう。パソコンという便利な道具があるので、何かのソフトを使って入力する。決定版と言うべきソフトがないので、自分の好きなソフトを選ぶで構わない。設計の中の作業によって適したソフトが異なるため、作業ごとにソフトを選ぶはずだ。
　システム設計に限らず、書きながら考える方法は、検討内容を整理するのに効果がある。効果の程度は、検討する対象が複雑なほど増す。一般的に、ソフトウェアのシステムは複雑なので、得られる効果は非常に大きい。
　この種の効果を最大限に高めるためには、思い付いた事柄をどんどんと書き出すのが一番。その内容を分類したり並び替えることで、漏れている事柄を見付けたり、共通性を見出したり、問題点が明確になったりする。書いた内容を見て考えると、新しい事柄を思い付きやすく、それを書き加えた内容を見て、また新しい事柄を思い付く。このように、考えることと書くことが一体化するため、思考の効率を相当に高められる。
　迷って前に進まない場合も、それを打開するための方法を考える。何を調べたら解決するのか、誰に尋ねたらヒントを得られるのか、どんな実験をすれば判断材料が得られるのかなど、思い付くことを書き出す。それらを見て、どれが一番役立ちそうかを判断し、すぐ実行に移す。ダメなら次を実行し、全部ダメだったら別な手を考える。このように、壁に突き当たったときも、書きながら考える方法は効果がある。
　システムの設計でも、このように作業を進めるのは必須だ。何も書かずに困って悩んでいる時間をなくし、どんどんと書きながら検討を続ける。こうすると、設計する内容が次第に明確になっていき、詳細な仕様に近づく。これが、設計作業の良いやり方である。

検討しながら書ける形式を、仕様書に採用すべき

　検討する際に書いた内容が、レビューやテストに使えないとしたらどうなるだろうか。レビューやテストの前に、別な形式に書き直す手間が生じてしまう。これは大変な無駄なので、そうならないように配慮する。
　作成の手間を限界まで減らすためには、検討の際に書いた内容が、レビュー、テスト、保守などの目的に、そのまま利用できるとよい。保守で利用するのは、最終的に残す仕様書なので、これも含められると、余計に作る無駄がほとんど生じない。
　それが可能となるように、３つの目的ごとで、何が求められるか明らかにする。まずレビューでは、検討の過程を中心に見ながら、設計結果と整合性があるかを判断する。テストになると、検討の過程は関係なく、設計結果であるシステムの仕様を見る。保守では、システムの仕様を中心に見るが、各機能が決まった理由など、検討の過程も一部見る。こうしないと、仕様を変更するときに見落とす点が生じやすいからだ。
　以上をまとまると、仕様書に書く内容は、検討過程と設計結果の２種類だと分かる。もう少し詳しく表現すると、以下のような内容になる。

仕様書に含まれる主な内容

・設計の過程に関わる情報 　　・システムの目的や期待される効果 　　・システムの目的から実現方法までの流れ 　　・設計の途中で検討した項目 　　・検討項目ごとに挙がった事柄 　　・事柄ごとの評価と、採否判定の結果と理由 　　・判断のために行った実験などの資料 ・設計した結果であるシステム仕様 　　・外部仕様：外部から見た機能の定義 　　・内部仕様：機能を実現するための方法 　　・利用仕様：使い方や運用の方法

　設計の過程と結果を分けるのは、非常に重要だ。設計の過程では、同じ目的の機能に関して、複数の仕様が挙がる。同様に、その機能の実現方法も複数挙がる。こうした情報が結果とまざると、どれが正しい仕様なのか分かりづらくなり、勘違いによる余計なトラブルを生じさせる。
　そうならないように、設計の過程と結果を明確に区別できる工夫を採用しなければならない。どちらも書類として作成するので、デザインを大きく変える方法がよい。仕様書の書式をテンプレート化して利用するので、最初から区別して作っておけば、間違うことはないだろう。
　レビューでは両方の書類を見て、設計の過程と結果で整合性が保てているか調べる。他の目的でも、必要な方を見ればよい。

設計の過程と結果は、異なる仕様書体系になる

　仕様書を設計過程と設計結果に分けたとき、その中身はどのようすべきなのだろうか。これらは、求められる点が大きく違うため、それぞれ別々に設計しなければならない。つまり、異なる仕様書体系を採用する。
　設計過程の仕様書体系は、内容が検討しやすい点を重視して決める。設計者にとって検討しやすい形式は、レビュー担当者にとっても検討しやすいものとなり、仕様書の利用目的の１つであるレビューの容易さも実現する。
　設計過程の検討は、大きく２つに分けられる。１つは、システムの目的から設計結果までを求めるという、中心的な流れだ。この検討を数個の工程に分け、工程ごとに検討内容をまとめるとともに、工程間の整合性も検査する。最初は問題点や原因を調べ、解決に必要な機能を求め、それをシステム仕様へとつなげる。
　もう１つは、使いやすさ、変更のしやすさ、エラー処理といった個々の検討項目だ。こちらは、検討項目に関係する箇所を洗い出して分類し、それぞれどのように対応するかを決定する。この判断が、最終的な設計結果に反映する。
　この２つ以外に、判断のために行った実験などの資料を、必要に応じて加える。以上を整理すると、設計過程の仕様書体系の概略は、以下のようになる。

設計過程の仕様書体系の概要

・システムの目的から設計結果を求める流れ 　　・問題点や原因から解決方法を検討 　　・解決方法からシステムの基本条件を検討 　　・基本条件から具体的な仕様を求める ・途中で検討する個々の項目（検討項目ごとに作成） 　　・検討項目に関係する箇所の洗い出しと分類 　　・分類した事柄ごとで対処方法を検討 ・その他：判断のために行った実験などの資料

　設計結果の仕様書体系の方は、システムの種類によって異なるが、概要だけは共通している。システムの外部仕様、内部仕様、両者の関係、利用仕様の４つに分かれる。内部仕様の細かな仕様だけは、必要な箇所だけ作成して構わない。省略できるのは、細かな外部仕様が決まったとき、そのままプログラミングできて、実現方法を細かく検討する必要がない場合だ。これらをまとめると、次のようになる。

設計結果の仕様書体系の概要

・外部仕様：外部から見た機能の定義 　　・外部仕様の全体像（構成） 　　・構成要素ごとの細かな仕様 ・内部仕様：機能を実現するための方法 　　・内部仕様の全体像（構成） 　　・構成要素ごとの細かな仕様（必要な箇所だけ） ・外部仕様と内部仕様の関連付け ・利用仕様：使い方や運用の方法 　　・システムの標準的な使用方法 　　・問題領域で発生する例外への対応方法 　　・運用の流れ、運用ルールや制限事項 　　・トラブル発生時の対処方法

　利用仕様だが、システムの使用者に渡す使用説明書ではない。システム設計で検討した内容のうち、使い方に関わる部分を記述する。たとえば、問題領域で必要となる作業が、システム側のどの機能を使って実現しているかの説明だ。また、１つの機能ではなく、複数の機能を組み合わせて実現するとか、作業側から見た制限や注意点なども書く。こういう形で整理すると、問題領域で必要となる作業が明らかになり、機能の漏れを見付けやすい。あくまで、システム設計の質を高めるために作るのである。当然ながら、細かな操作方法は対象としない。
　利用仕様に含まれる「問題領域で発生する例外への対応方法」の中身だが、システム化が難いために、運用で対応すると判断した内容などを、整理して解説する。こうした点までキチンと検討して明らかにするのが、良い設計だ。

設計の過程と結果を、段階的に作り進む

　実際の設計では、最終的な結果を一気に作るわけではない。何個かの工程に分けて、段階的に検討を続け、最終的な設計結果を得る。その間にいくつものレビューが入り、製作段階で小さなテストが、最後の方で本格的なテストが実施される。
　こうした流れになるので、仕様書の作成もそれに合わせる。設計過程の仕様書は、複数の工程に分かれた形式にする。「システムの目的から設計結果を求める流れ」の仕様書なら、中心となる工程に沿って、１つずつ作り進み、工程間の整合性も検査する。「途中で検討する個々の項目」は、検討項目ごとで少数の工程に分け、これも１つずつ作り進む。
　設計結果の仕様書の方は、設計の工程ごとに分かれない。設計が進むに従って、より詳しく記述していく形だ。つまり、書き加えたり書き直したりして、内容が段階的に詳しくなっていく。もし工程ごとの結果を後で調べたいなら、途中の段階をコピーして保存する。
　利用仕様に関しても、書けるものはできるだけ早目に書く。たとえば、標準的な使い方や問題領域例外への対処を書いているとき、システムの不具合が見付かることもあるからだ。ただし、設計が上手でない人や、知らない分野で設計した場合は、後から仕様変更が何度も発生して書き直す羽目になるため、使用方法などを最後に書いた方が良いだろう。
　設計結果の仕様書は途中状態を残すので、どれが最新か区別できるように、日付やバージョン番号を含めなければならない。設計過程の仕様書も、後工程の検討中に不具合が見付かり、後から変更することもある。こちらも最新を区別できるように、日付やバージョン番号を付ける。
　このように、設計過程と設計結果の仕様書は、体系が違うだけでなく、作り進み方も異なる。それぞれに合った形で書いていき、開発の最後の両方が仕上がる。

似た記述を体系化して別に用意し、書く作業を軽減

　システムの設計が詳細な段階へ進むほど、他のシステムと共通する内容を記述する機会が増えてくる。システム側に関係することなら、エラー処理の方法は同じ場合が多い。設計した理由まで書くので、システムごとに記述していたら、同じ内容を何度も書かなければならない。こうした作業は無駄だし、間違いを生みやすい。
　複数のシステムで共通する内容は、基本的に別な書類として作成する。対象となるのは、エラー処理の実現方法のように、システムの内部仕様だけはない。値を入力していない金額項目はゼロとして計算するといった外部仕様も、共通の内容なら別に書く。
　この種の内容は、利用しやすく体系化することが大切だ。個々の内容にIDを付け、簡単に参照できる形にする。また、途中で追加できるように、階層化したID体系を採用する。各システムでも機能などにIDを付けるため、絶対に重複しないID体系を割り当てなければならない。
　書類の内容だが、名称、設計内容、設計理由、利用条件の４つは最低でも含める。名称は、ほどほどの長さで表現し、IDと一緒に用いる。IDだけだと分かりにくいからだ。設計内容は、どのように設計するかを説明し、どうしてそうするのかを設計理由に書く。それをどんなときに用いるのか、どんな条件を満たしたら使って良いのかなどを、利用条件で示す。それ以外にも、必要に応じて注意点などを書き加えればよい。
　各システムの仕様書では、IDと名称だけを指定するだけで済ませる。簡単に参照できるように、データベース化しておくと良いだろう。この方法なら、設計理由までキチンと書きながら、無駄な作業は生じない。
　こうした共通の内容は、設計ノウハウの集まりでもある。地道に蓄積して、どんどんと利用し、同じような失敗をやらないようにする。また、若い技術者にとっては、蓄積された内容を全部読むことが、効率的な成長に役立つ。

　以上のような仕様書体系を採用すると、設計しながら仕様書が書けるようになる。また、設計者自身が検討内容を評価しやすいし、レビューもやりやすいので、設計の質も格段に向上する。おまけに、検討の途中で迷うことが減るため、設計の作業効率まで向上する。いろいろな面で利点が多い。
　良い仕様書に仕上げるためには、もう１つ大事なことがある。説明内容を分かりやすく正確に書くための作文能力だ。これは仕様書以外の作成でも役立つので、誰もが身に付けておくべき能力といえる。

（2001年７月30日）