仕様書はどこまで書けばよいのか？

新人にソフトウェア開発の作業手順を教えていると、思いも寄らぬ質問を受けて戸惑うことが有る。例えば、先日はこんな質問を受けた。

「仕様書はどの程度まで書けばよいのですか？」

あまりにストレートな質問なので何と答えるべきか一瞬戸惑ってしまったが、考えてみれば仕様書の記載をどの範囲でどのような粒度でどこまで書くべきなのか？という基準は何も存在していないのだ。品質管理の規定に従ってレビューや照査・承認のプロセスは存在するものの、それは書いた後で行われるプロセスだし、ソースコードと違って「動作する」「動作しない」という明確な境界線も存在しない。内容にモレや矛盾が存在する仕様書は珍しくないし、書き手によって仕様の構成や内容が違うことも有るのだ。

しかし、実際問題として仕様書を上手に書く人はいるし、チーム内には失敗事例を元にまとめた仕様書ガイドラインも存在している。だから「完璧ではないけれど、それなりに及第点をもらえる」書き方は存在するし、そのノウハウを共有すれば誰でも同レベルの作成作業が出来るのではないかとも思う。そんな背景を説明しつつ、こんな点に留意して書くことが必要だと説明してみた。

背景知識がない人が仕様書を読んで、全員が同じ対象をイメージ出来ることが必要。だから新規開発では開発対象の背景や理由、用語の定義などが重要であり、派生開発では変更点やその理由、変更方法を明記することが特に重要になってくる。
具体的なイメージが湧きやすいGUI関係の仕様は読み手も理解しやすく、書く側の難易度も低い。要求仕様書は、対象が広い上に抽象度の高い記述が求められるので書く難易度も高い。
日常会話でも些細な言い回しの違いで誤解が生じるのと同様、仕様書に記載された一つの文章でも読む人によっては様々な解釈をしてしまうのが実情。防御的プログラミングではないけれど、誤解を生じさせないための「防御的な仕様の記述」が必要。
文章だけで構成された仕様はどうしても曖昧性が残る。UMLのシーケンス図やGUIなど、図面化した方が分かりやすく誤解も生じにくいので、可能な限り仕様に含めた方が望ましい。
仕様書として完結していることは必須。他の資料への参照が載っているのは良いが、資料を読んだだけでは理解出来ず、内容に対する疑問点が出てくるようでは記載が不足している証拠。
仕様書の記載は詳しく書いていくとキリがない。ソースコードを読めば分かるようなことは基本的に記載不要であり、もう少し抽象度の高いレベルで説明を行うことが求められる。
障害が発生しやすいのは、仕様書に書かれていることより、書かれていないことの方が多い。だから、チェックリストで記述モレを防いだり、表を記載してモレがないことを明示することが望ましい。
仕様書は、開発対象を分析、評価、設計したものを資料化したものであり「設計過程のまとめ」という役割を果たす。思いついた文章だけ書き並べてもそれは仕様ではないし、資料の存在しない開発はまともな設計が行われていない可能性が高い。
ソースコード同様に仕様書も長い期間にわたって修正、追加が行われる。ずっと後になって派生開発を行う人が読んで理解出来るような記載を行うことが重要。

究極的にはVDMなどの形式仕様記述を使って、誰でも同じ理解に至る記載方法が必要になるのかも知れないが、そのような開発技法を今すぐ開発現場に持ち込むことはなかなか難しい。また、文章で曖昧な仕様書しか作れない開発者には、仮にどのようなツールを与えても動作が明確に定まらない曖昧なものしか作れないような気もする。そんなわけで、文章という厄介な性質のものを扱いつつ、自分の頭の中でモレ・矛盾の無い論理を築き上げていく能力が、今の開発者には求められるのではないかと思う。

極論すれば，形式仕様記述を使わずとも，C言語のような実装言語でも，「精緻に分かりやすく書こう」という心がけを徹底し，それがそのエンジニアの脳ミソへの鍛錬として働くのであれば，形式仕様記述とほぼ同様な効果が得られるのではないかと，今回の原稿を見ている中で感じました。
http://techon.nikkeibp.co.jp/article/TOPCOL/20070216/127811/