仕様書の書き方 - CATchy programming

仕様書というと以下の例のように行の先頭に番号が付いているものをよく見かけます。噂によると、「全てに番号を付けろ」などと言う人が昔いたようですが(今でも？)、何故そのようなことが言われたのでしょうか？

1. 顧客情報をほげほげの条件で検索する。
2. 1. の検索でデータがあった場合。
    2.1. データを１件取り出す。
    2.2. 2.1. の情報をキーに あばば を検索する。
    2.3. 2.2. で検索したデータを出力する。
    2.4. データがまだある場合、2.1. に戻る。
3. 1. の検索でデータがなかった場合。
    3.1. 「データがありませんでした」と出力する。
4. 終了処理をする。

この章では、このような番号の付いた仕様書のことを、「番号付き仕様書」と呼ぶことにしましょう。番号を付けろと言うのは、例えば上の例で言うと、「1. の検索で...」とか「2.1. に戻る。」と書くときに、番号がないとどの処理か特定できないから必要だと思い込んでいるのだと、私は思っています。

では、本当に番号がないと困るのでしょうか？番号を使わずに書き直してみましょう。

・顧客情報をほげほげの条件で検索する。
if (検索でデータがあった場合) {
    for (全てのデータに対して) {
        ・データを１件取り出し、これをほげほげのキーとする。
        ・ほげほげのキーをキーに あばば を検索する。
        ・検索したこのデータを出力する。
    }
} else {
    ・「データがありませんでした」と出力する。
}
・終了処理をする。

C言語風の疑似コーディングで書いてみましたが、番号がなくても、特に困ることはありませんでした。

しかも、こちらの方がすっきりしていて見やすいと私は思いますが、あなたはどうですか？それに、番号付き仕様書にありがちな不明確さなど(後述)がなくなっています、
こちらの方を「疑似コーディング仕様書」と呼ぶことにします。

つづく...

★番号付き仕様書にしても、疑似コーディング仕様書も、これらは仕様書の形態の１つであり、これが仕様書のすべてではなく、あくまでも内容を伝えるための付属品でしかないと考えた方がいいかもしれません。仕様書の真髄は別のところにあります。

「仕様書」という名前の付いた文書は世の中にはたくさん存在しています。しかし、本当の意味での仕様書と呼ばれるべきものは、そのうちのどれぐらいの割合を占めているのでしょうか？

たぶんほとんどの人は「番号付き仕様書」の例の様な文書を仕様書だと思っているのではないでしょうか？私は、あのような文書は仕様書だとは思っていません。あれは単なる「ソースコードの説明書」です。ソースコードの説明なら、ソースコードそのものを見るか、そこに書かれているコメントを見さえすれば、用は足りてしまいます。(たまに、ソースコードの説明書にもなっていないような仕様書を見かけるんですけどねぇ...)

仕様書に見せかけているソースコードの説明書には、存在する意義はありません。だって、ソースコード中のコメントと同じなんですもの。

では、本当の意味での仕様書には何を書かなければならないのでしょうか？例えば、あることを実現したいと考えたとします。それを実現するための方法は通常、複数存在します。その内の１つを選択して、設計をし、実装を行います。ソースコードの説明書には、この実装の部分の説明しか書かれていないことになります。どうして、そのあることを実現したいのか？どのような実現方法があるのか？複数ある実現方法の中から１つを選択した理由は？どのような経緯でどのように設計を行ったのか？などの重要なことが書かれていないのです。これらの情報は、そのシステム(だとしよう)を理解しようとしている人にとって、一番知りたいことなのに。

たぶん、設計者は頭の中だけで設計を行い、最終的にでき上がった実装部分だけの説明を書いていたのでしょう。しかし、設計者の頭にだけしかない情報は、他の人は見ることができません。ですので、その部分に間違いや問題があっても誰も指摘できないのです。頭のだけで設計を行わないで、その部分も仕様書に書くようにしてください。頭の中だけで考えていても分からなかったことが、書くことによって、考えをまとめることができることもあります。(しないことも、たまにありますけどね...)
また、その文章が他の人の問題解決の手がかりになることもあるかもしれません。

簡単な例を書いておきます。(あくまでも例なので、内容は気にしないでください ^^;)
ソースコードの説明書:

◆販売促進メールの送信処理:
  ・顧客情報と売上情報から過去３ヶ月購入していないレコードを検索する。
  if (検索でデータがあった場合) {
      ・メールの内容を読み込む。(すべての顧客で共通)
      for (全てのデータに対して) {
          ・今月のおすすめ情報メールを送信する。
      }
  } else {
      ・「データがありませんでした」と出力する。
  }
  ・終了処理をする。

仕様書:

◆販売促進メールの送信処理:
・リピーターを増加させるため、最近(３ヶ月)「e-WebShop」で購入をしていない顧客
　に対して「おすすめメール」を送信する。
・顧客の商品の購入傾向を把握して、各顧客ごとに One-To-One でメールを送信した方
　が、より高い効果が期待できると思うが、リリースまでの時間がないので今回は見送
　り、すべての顧客で共通の内容とする。
・具体的な処理は以下のとおり:
　(※上記「ソースコードの説明書」の内容)

★もうちょっと例は身近な内容で行いたい。例えば、缶コーヒーを買いに行くお買い物ロボットの例とか... 身近じゃないか...

このように、設計の意図を書いておくことにより、これを見て実装を行うプログラマも、内容をよりよく理解しやすくなります。これによって、設計者と実装者の間の誤解が生じる可能性を低くすることができるでしょう。

また、設計の経緯を記述しておくことで、どうしてそのような設計になったのか？ということを忘れてしまうことがなくなります。実はこれ、よくあることで、「なんでαという方法ではなく、βという方法を採用してしまったんだろう？αの方が速いのに...」と設計をαでやり直した後で、αでは重大な欠陥が有ったことを思い出し、βに戻すということってありますよね？(ないですか？私だけかな？記憶力が弱いもので...) っと言うわけで、こういったムダがなくなります。

もちろん、設計の意図を記述する時間が余計に掛かりますが、その分ムダな作業(設計のやり直しや、誤解による実装のやり直し)がなくなります。それに、メンテナンスがしやすくなり、メンテナンス費用を下げるという効果もあります。いわゆる、「急がば回れ」というやつです。

つづく...(かな？)