Excelの仕様書の決まっている部分と、フリーフォーマットの部分

前のブログで、Excelの仕様書は、入出力用、プログラム用、テスト用が多く作られると書いた。今回は、そこに書かれる内容を説明するわけだが、そのまえに一言。

　これは、あくまでも、そういうのをExcel書く場合、意味があるというだけで、べつにこれらのものを、Wordで書いてもいいし（事実、書いていることも多いと思う）、これ以外のドキュメントをExcelで書いてもよい（書いたほうが管理は便利）。

　実際は、プロジェクトマネージャーさんの好み。

　では、本題。

---

入出力用、プログラム用、テスト用でかく内容。

・入出力用のドキュメントで書く内容
　これは、逆算して求められる。
　このドキュメントから、テーブル入出力インターフェースと、ＤＤＬが作成される。
　ということは、そこに書かれる情報は、仕様書のどこかに書かないといけないということ。あとは、テーブル入出力インターフェースと、ＤＤＬを自分で分析して考えてくれ。それがＳＥの仕事なのだから。。。

　テーブル入出力インターフェースのプログラムは、プロジェクトごとに違う。ということは、この仕様書の項目も、違うことになる。
　このドキュメントは、備考は自由にかけるが、フリーフォーマット部分は、ないことが多いと思う

・プログラムのドキュメントで書く内容
　本来は、以下の３つの部分に分かれる
　　（１）JavaDocで書くような、メソッド、クラスの情報
　　（２）このクラスまたはメソッドが扱う入出力データ
　　（３）実際のメソッドの内容（手順）

　本来は、（２）の書かれた入出力と、外部設計書の間に矛盾がないか（新しいデータ、テーブルなんかをつくっちゃってないか、外部定義書に書かれているデータを入力し、規定のデータを返しているか、意味を取り違えていないか）を確認し、（２）で示されたデータを使って、（３）が、処理加工されているかどうかを確認できるようにしておく。

　しかし、前のブログでかいたように、オブジェクト指向がはやっている最近は、（２）を書かない。なので、定型部分は、（１）の部分の内容（ＪａｖａＤｏｃに書いているようなこと）、フリーフォーマット部分に、（３）の内容を書く。
　なお、フリーフォーマット部分に、サンプルデータも書くこともある。

　ちなみに、（３）の内容中、プログラムの説明部分が、構造化分析における、ミニスペックに当たる。

・テストで書く内容
１テスト１レコードの部分は、定型フォーマット。それに付け足すサンプルデータなどが、付録として、フリーフォーマット部分に書く

---

って、こんなところかな。。

開発の仕様書全体における、Excelの仕様書の位置づけとその理由、オブジェクト指向との関係など

　いままで、「Excelの仕様書」とか、「フリーフォーマット部分」とか、書いてきましたが、これ、「Excelの仕様書」を見たことない人、さっぱり意味通じませんよね！

　ということで、今日は、「Excelの仕様書」というのは、どういうことが書かれているか、その種類と、平均的な内容についてと、オブジェクト指向で作成するドキュメントと、どこがどうちがい、なぜ、違うのかを書きます。

---

まず、仕様書って呼ばれるものは、こんなかんじかな？
（ＳＡ，ＵＩなどは、意味が通じない人は無視してください。一部の人たちがいう、呼び方です）

１．発注仕様書
　契約書についている場合がおおい。
　プロジェクト憲章になる場合もあるが、ふつうＳＥさんが書くものではない
（といいつつ、ウィリアムのいたずらは、何回か書いた＝客が書くより、仕事を請けるほうが書く場合が多い）

２．要件定義書
　要求仕様書になっている場合もあるし、暴言すると、概要設計書も、似たようなもんだ。ＳＡのドキュメントは、ここに入る

３．外部設計書
　システム外部の見た目を書くことが多い（かならずしも、そういいきれない場合もある）。ＵＩドキュメントは、ここに入ると思う。
　テーブル構造など、入出力のドキュメントは、ここに入れるべきか、詳細に入れるべきか。。

４．内部（詳細）設計書
　システム内部のプログラムについてのドキュメント、こんなもんかなあ。
　・プログラムに関するドキュメントと、
　・メソッド間で渡されるクラス（ようするに、バリューオブジェクト）の定義
　・システム共通定数
　・システムメッセージ定義（エラーメッセージとかの定義）
　ＰＧのときのドキュメント。
　自動生成するために作成するドキュメントは、ここに入ってくるね。たいてい。

５．テストドキュメント
　ＰＴ，ＩＴ用ドキュメントなど。
　最近は、２種類のものがある
　・１テスト、１レコードとして、表形式で書く。
　　データや手順に関しての詳細を別紙として添えるこの別紙がフリーフォーマット）
　・１テスト、１枚（または１シート）として書く
　　この紙の中に、そのテスト分の、テスト方法などをかく
　もちろん、この２つをあわせて、１テスト１レコードのものを、一覧としているものもある。

ちなみに、ドキュメントとしては、あと、進捗関連、バグ関連、フレームワークなどの説明、開発用インストール関連、などなどあり、進捗関連、バグ関連が定型フォーマット。

---

　で、上記のドキュメントを書く本来の目的は、発注仕様書に書かれた成果物（出力）が、各処理において論理的に矛盾なく、出力されているかどうか、要件をうけて、外部仕様、それを受けて内部仕様という仕様の一貫性が保たれているかを確認すること。

　そのためには、処理と、データ入出力が、ドキュメントのフォーマットの中で、定型化されていないといけない。

　しかし、オブジェクト指向で行った場合、開発初期の段階でユースケースを作り、そこからクラス→プログラムに展開してしまう。
　このユースケース内には、ＤＦＤと違い、データの詳細とその流れを記載しない。

　したがって、オブジェクト指向で考えていった場合、この定型フォーマットは使いにくい。そこで、現在、定型フォーマットの中から、入出力記述を抜いてしまっているものもある（それでいいのか。。いいわけない。ドキュメント作っている意味がない）。

　オブジェクト指向の人から見ると、したがって、（データの裏をとるために仕様書を作っているのに、その部分がないんだから）仕様書って、意味ないじゃん！っていうことになる。。。

---

　ということで、仕様書全体は、以上のとおり。そのうち、現在、Excelでの定型フォーマットの多くは、以下の部分に使われることが多いと思う。（ほかのドキュメントはWordや、お絵かきソフトが多い）。

・（「３．外部設計書」であげた）入出力関連
　・画面／ウィンドウのようすを書いたもの(Wordのこともある）
　・テーブル定義書（ＥＲ図の場合は、WordやVisioのほうが、書きやすい）
　・ファイルフォーマット定義（最近、フリーフォーマットなんで、作らないかな？）
　・通信関係のデータグラム（っていったっけ？レコードに相当するやつ）の定義
　　→ソケット間通信などがあれば
　などなど

・（「４．内部（詳細）設計書」であげた）プログラム関係
　・クラス内の変数、メソッドの引数・帰り値と処理内容などをかいたもの
　・引数中、バリューオブジェクトの定義
　・システム共通定数
　・システムメッセージ定義（エラーメッセージとかの定義）

・（「５．テストドキュメント」で書いた）テスト関連
　・テスト仕様

---

　これらのドキュメントが、なぜ、(Wordでなく）Excelで書かれるのかについて。

・入出力関連の場合
　入出力インターフェースと、ＤＢスキーマの矛盾をなくすため、ＤＢ追加・変更に関しては、ＤＢ管理者が、入出力操作クラス（メソッド）、ＤＢ用ＤＤＬを自動生成し、そのうち、プログラム部分を構成管理担当者に渡すというしくみに（おおきなシステムだと）する。その自動生成が、しやすく、構成管理の人やＤＢ担当者、開発者が、「紙に出して」みやすいのがExcelだということ。

　紙でないと、これらのドキュメントを１０個くらいならべて、比較するときめんどう（うーん、１メートルくらいの見やすい画面のディスプレイが出来れば、紙がいらないんだけどね。。）

・プログラム仕様書
　プログラムを作成する前に、インターフェースの打ち合わせをする。
　その打ち合わせ資料として使うのにExcelだと、見やすいというのがあるが、最近はスタブをあらかじめ作成し、JavaDocで済ますということも多くなってきた。

　→つまり、この場合、スタブを作成する必要がある！

　スタブがないと、この場合、JavaDocが作れず、インターフェースの打ち合わせが出来ない。スタブも作成しないで、ドキュメントも作らず、インターフェースをあわせようというのは、無理。

　ただ、JavaDocの方法でかかれると、テストの自動生成に、データを持ってくることが出来ないので、リスクは、大きくなる。

・テスト仕様書
　１テスト１レコードの場合、Excelが書きやすいからだと思う。
　たしかに、テスト仕様書を自動生成することもあるが、そのためにExcelというわけではない気がする。ひょっとすると、成り行きかも？？

---

　ごめんなさい。思ったより長くなるんで、この記事は、ここまでにして、続きを次の記事に書きます。