ソフトウェアに仕様書は必要か

ここに、次のような文章がある。
『▪️コンストラクションの成果物であるソースコードは、多くの場合、ソフトウェアを正確に書き表した唯一のドキュメントである
多くのプロジェクトにおいて、プログラマが入手できる唯一のドキュメントは、コードそのものである。要求仕様書や設計書は最新の情報を反映していないことがあるが、ソースコードは常に最新である。』

あいにく、出典は忘れた。

設計文書とソースコードが乖離することの問題は、私の周りでもよくある。残念ながら、私自身の文書、コードにもなくはない。その事実が、世界共通、人類共通なのだと改めて思い知らされた。自分だけではないのだと安心したり、それほどに厄介な問題であるのだとため息したりである。

ソースコードと設計文書を一致させる・・・こういう類のことは、とかく、人間というのは不得手なのである。完全機械化でもされない限り、撲滅は無理だ。できもしない「文書とコードの同一化」を目指すくらいなら、文書を減らすことを考える方がいい。

考えてみたことはあるだろうか。
そもそも、設計文書とソースコードは情報が重複している。ある意味で、当たり前である。同じものに対する表現なのだから。「ソースコードは改修しても設計文書の修正は忘れる」といった事態に陥る理由の一つがここにある。ソースコードで修正した内容を設計文書にも反映させるというのは、結局は、ソースコードで改修した内容をそのまま設計文書に書き写すだけだ。重複した情報を、あっちもこっちも書き直すというのは、非効率以外のなにものでもない。そのような重複した情報は少ないに限る。

無くした方がいい仕様書の筆頭格が「関数仕様書」なるものである。「仕様書」というものは兎角様々な名称を持つが、ここでいう「関数仕様書」とは、関数の名前、シンボル、引数の個数、及び型を定義した文書である。これは、今や過去の遺物なのである。

一昔前のコーディングというと、ダム端末でエディットした。「ダム端末って何？」と思われる方も多いかもしれない。古いSF映画だと、キーボードをカタカタやると画面に緑色の文字が入力されていくようなコンピューターをときどき見ることがあるが、ダム端末というのは要するにアレである。英語の「dumb terminal」がそのまま日本語になったものである。「dumb」は「間抜けな」とか「バカ」といった意味であり、文字通り文字を入力して画面に文字を出力するだけの端末である。昔はコンピューターそのものが高価で、一台のコンピューターを複数の人間で使用した。そのための端末がダム端末だったわけである。バカ端末かもしれないがそうやって使えるだけでも貴重な資源だった。だがこの環境では、同時に編集、参照できるソースコードファイルは1つだけである。もし、関数仕様書がないとどうなるか。

ある関数を呼び出そうとする。はて、引数はなんだったかと悩む。引数はもとより、関数のシンボルでさえあやふやだ。仕方がないので編集中のエディットを一旦中断して、該当する関数を記載しているソースコードファイルを開くしかない。ようやく関数のコーリングシーケンスがわかったとして、元の編集ファイルに戻った時には、再び忘れていないとも限らない。やむを得ず、コーリングシーケンスをメモするハメになる。キーボードの横には紙と鉛筆である。当たり前であるが、コーディングするにも時間がかかる。

加えて、コメントに日本語を用いるなど論外だった。文字コードが合うの合わないのというレベルではない。日本語入力フロントエンドプロセッサそのものがないのだから、どうしようもない。まれに日本語入力可能だとしたところでが、文字コードによる入力である。結局のところ日本語入力はあきらめ、英語入力を強いられる。断るまでもないが、英語の辞書はもちろん紙の辞書だ。関数の概略、引数の解説など、拙い英語のオンパレードとあいなる。

このような開発環境では、ある程度は関数仕様書を書いてからでないと、とてもではないがコーディングできたものではない。使用する関数のシンボル、引数の数、型などをもれなく記憶できるものではないのだ。

だが、現代は違う。

まず、他の関数を参照しようとして、編集中のエディタを中断する必要はない。どんどんファイルを開いて、必要であれば横に並べることも可能だ。

どのファイルを参照すればよいのかを忘れたとしても、やすやすと検索できる。優秀な統合環境であれば、タグジャンプできたり、果てはツールチップで随時引数を表示してくれたりと至れり尽くせりである。

関数仕様書に書くはずだった仕様は、ソースコード中にどんどんコメントとして記載すればよい。日本語コメントだって、お安い御用だ。

これを、何故わざわざワードプロセッサで書かねばならないのか。結局のところ、昔の慣習を引きずっているだけではないのか。

見た目がいいから？
しかし、見た目の良さなど、たいした足しにもならない。

「ソフトウェア設計の経験が浅いものには、いきなりソースコードではなしに設計文書を書く方が設計の良し悪しがわかりやすい」という意見もあるかもしれない。しかし、これについても、理解しがたいコードを書く者は、得てして設計文書も理解しがたいものとなる。従って、これもまた意味を成さない。

「フローチャートがないと理解し辛いコード」というのがあるとしても、それも仕様書が必要という理由にはならない。フローチャートがわかりやすくしてくれるのではなく、コードの記述がまずいというだけにすぎない。フローチャートに書き起こすひまがあるなら、コードを書き直した方がよい。そもそも、設計文書を読まなくても理解できるようなコードである方が望ましい。すなわち、よりよいコードであるほど、設計文書は不要ということになる。

設計文書さえあれば、そのソフトウェアを誰にでも引き継げるというのも幻想である。引き継ぎやすいソフトウェアは設計文書がなくても引き継げる。逆に、引き継ぐのが困難なプログラミングは、設計文書も理解しがたいものであり、すなわち、設計文書があってもやはり引き継ぐのは難しい。

私自身は、設計文書皆無が「理想的」であると考えている。

とは言え、私にも、どうしても必要とする仕様書がある。状態遷移表である。これは、ソースコードでは決定的に不足しているものを補ってくれる。それは、二次元で表現できるということである。ただのテキストファイルにすぎないソースコードではなし得ないことだ。仕様書をなくしたい私としては、言語仕様が進化してくれるのを願うばかりである。

いずれにしても忘れてはならないのは、「ソースコードが唯一のドキュメントである」ということである。ソースコードとは別に仕様書がいるのだとしたら、己のソースコードの出来が悪いと考えるくらいでちょうどいいのだ。