仕様書の質は、仕様書の書式である程度決まる

X年前に作成された仕様書の書式で、今回のJavaのシステムの設計書を書いてください。と言われ、その設計書の書式を見てみると中途半端にJavaの事が書いてある。パッケージ名とかクラス名とかメソッド名とか、JavaBeansの変数名だとか。それはプログラマが実際に書く時に決めれば良いだろうにと思いました。

大規模システムで画面とかがコード管理されている場合は、機械的に記入しても良いんですけど、そうではないので変数名を考えている時間がもったいない。いつ時点での仕様書かにもよりますが、まずは実現すべきことを自然言語オンリーで書けば良いと考えています。

中途半端に書くとプログラマは"その通り"に書くので、実際にメソッドを分割したり、クラスを分割したりする事をしなくなり、1つのクラスが莫大に大きくなったり、共通化をしようとしなかったりする。そうならないために、フレームワークがあり、フレームワーク内ではどのようにプログラムを作るべきか。そういう開発指針的なものは仕様書とは別に共通の資料として用意する必要があると思っています。

仕様書の読み方、仕様書からプログラムの作り方、プログラム構築の指針。こういう資料はあると無いとで最初のとっかかりが随分違いますし、後々の品質の均一化にも影響が出ます。特に限定するわけではありませんが、オフショア開発を例に取ると指針が無くて自由自在にプログラマに開発を行わせると一貫性の無いプログラムが大量生産されて、受入テストが大変だったり、保守性に乏しくなったりしました。

表題に戻りますが、仕様書の質はある程度仕様書の書式で決定されると思っています。書式によって書くべき内容が決定されますから、全部フリー入力でも無い限り書くべき内容というのが書式によって指示されます。その指示される内容が現在の開発スタイルには合わなかったり、情報が足りなかったりするとその半端な品質で仕様書が均等化されてしまいます。

機能の説明ひとつとっても、「機能詳細」という欄が一つだけあると、上から下まで細かく書いてしまい、読み手は概要を掴むのに一苦労します。そこに「機能概要」という欄があれば、ざっくり機能を掴んだ上で、詳細を読み進める事ができます。「機能詳細」についても、中に「イベント」という欄があれば、その機能が呼び出される元を記述する事ができます。

知りたい情報から書式が起こされたのが最初だと思うのですが、その書式を作ったのがX年前というと、今の開発ではちょっと役不足。COBOLの仕様書から起こしたんだなんていう資料は昨今のJava開発ではちょっと書きづらい仕様書だと思いました。例えば最初からStrutsを意識された仕様書だったら、ActionとFormに分けて仕様書は書くでしょうし、詳細に詰めるとメソッドの定義から機能の詳細、入出力項目からバリデーションの詳細と掘り下げて書く事ができます。プログラムレベルまで考慮された仕様書は、設計書と言った方がしっくりきますけど、ここでは特に意識して言葉を使い分けていません。

汎用的な仕様書というのは、フリーフォーマットくらいで、ある程度は言語やフレームワークに依存した形の仕様書が開発を楽にすると思います。書式に合わない事は書かないのではなく、フリー入力の欄に書き入れれば良いと思いますし、プログラマの足かせのためのフレームワークというものがあるのならば、仕様を書く人のための足かせが仕様書の書式だといえなくもないかもしれません。

ということで…「仕様書の読み方.doc」はとても重要！