「読める」仕様書

　あなたのその仕様書は、「読む」ものだろうか、それとも「見る」ものだろうか？
　私はあるとき、私の仕様書に対して「これ読む気にならないね」と言われた。そしてその人は過去のプロジェクト（私は参加していない）の仕様書を取り出し、「こういうふうに図を多用するとわかりやすいでしょ」と言われたのだった。しかし、私にしてみれば何がなんだかさっぱりわからなかった。その人は、その図を指差しながら当時のプロジェクトを説明してくれたのだが、なるほどそれでやっとその図がわかりやすかったのだろうということがわかった。
　では、この人の仕様書は果たして良い仕様書なのだろうか？
　私は図によってわかりやすくなることを知らなかったわけではない。私は、意識的にそんな図は使わなかったのだ。たとえば、この人、あるいはこのプロジェクトにかかわった人がみんな退社したり、もしものことがあったりしたらどうなるだろうか？　残された仕様書を説明してくれる人がいなくなるわけである。このプロジェクトは永久に闇に葬られたということでいいのであろうか？　良いわけはない。少なくとも客先で稼動している限りは。しかし、ここに「嫌でも読みさえすればわかる」仕様書があったらどうだろうか？　残された開発者は、客に「すいません、担当者がいなくなりまして」と無様極まりないいいわけをするぐらいだったら、きっと仕様書を読むであろう。
　「読む」仕様書というのは、曖昧さを排除するのに大変都合が良い。いや、逆に図というのは本来、「曖昧」にしたり「抽象的」にするために理解の「助け」とするもののはずである。特にソフトウェアとは「見えない」ものなのだ（見えたらそれはハードウェアだ）。図で完璧に表現できるはずがない。また、表も図に準じる。データベースの仕様書をテーブル定義を記した表とER図で作り上げて満足しているのなら、もう一度考え直して欲しい。それぞれのフィールドが何のために存在するのかなどはしっかりと記述しているだろうか？　特に、すべてのテーブルに無節操に「削除フラグ」や「更新日時」なんてものをつけている場合は、どういうときにそれを使うのか（「削除するとき」物理削除のかわりに「削除フラグ」を使うではダメだ）をしっかり記述しておかないとあとで手痛いしっぺ返しを食らうことになるだろう。