ソースコードが仕様書だ

アンケートしてみた。
http://q.hatena.ne.jp/1217435141

「仕様書必要」でググると一番目が「Joel on Software」で二番目が「谷島の眼?ソフト開発に仕様書は必要？不要？」に出てきて、まあここ読めば十分という気がしないでもない。

少し前になるが「プログラミングできない元請けがプログラム設計書をレビューするという矛盾」とかを（トラックバックを含めて）読んでいると、

単に「仕様書」と書いたときの意味
仕様変更に対する温度差
業界の習慣、常識
開発規模

が違うと話が全くかみ合わないなあと思う。

当たり前の話だが仕様書は人間が読むもので、ソースコードは機械が解釈するものだ。仕様書がどのくらい必要か（あるいは不要か）というのは、どのくらい人間が読む必要があるかということだと思う。

とりあえず仕様書が何であるかということだと、基本設計書、機能設計書、詳細設計書があるとして、基本設計書にシステムの目的を、機能設計書にモジュールの役割や関係性を、詳細設計書に関数の仕様とかインターフェースを書くものかなあ、くらいに思っているが、APIやDB設計を機能と詳細のどっちに入れるのかとかその辺は人それぞれだろう。それはさておき、この中で最も重要なのは基本設計書だ。なぜかというと「なぜ」が書かれているから。

ソースコードからは、それがどのように動くかということは読み取れるが、なぜそう書かなければならなかったのかという理由が読み取れるとは限らないということがひとつ。（だからコメントには「なぜ」を積極的に書く必要がある）
もうひとつは、ソースコードが巨大な場合にはソースコード全部は読んでいられないし、全体の概要をつかんだ上でないと、ある部分のソースコードの意味や位置づけが理解できないから。私はスーパープログラマじゃないので、ソースコードだけでは全体をイメージできないことが多い。

逆に「ソースコードが仕様書だ」で済むケースは、こんなところだろうか。

コンパイラなど、プログラムの用途が明確
検索など、仕様が単純明快
自分しか使わない or 他のグループメンバーも仕様を熟知している（説明する必要がない）
仕様が複雑で自然言語で記述できない or 自然言語で記述するとかえって混乱を招く
ソースコード読むだけで頭の中で全部実行できる

私の場合、仕様書が重要というのは頭ではわかっていながらも、トップダウン的思考がなかなかできないので割と後回しにしてしまう毎日。仕事の大半は受託開発だが、仕様書とソースコードのどちらを重視するかは案件の性格によって決めることにしている。

単発の試作の場合はプログラム重視
- プロトタイプが神様
- 最初のフェーズでは、システムが意図したものになるか確認するためにプログラムを書く
改版や製品開発の場合は仕様書重視
- 仕様書が神様
- 最初のフェーズでは、実現可能性あるいは実用性の確認のためにプログラムを書く

いずれにせよ、担当者間で齟齬が出ないように、必要になったタイミングで全体像がイメージできる資料を用意することは大切だと思っている。
お客さんとの打ち合わせではフローチャートみたいなものも書いたりする。プログラマでなくても理解できることが多いからだ。後で読んでもすぐにわかるように（後から読んでも同じ理解になるように）、できるだけ単純なものが望ましいんじゃないだろうか。