業務システムの開発ドキュメント標準化 第４回：詳細設計書（前半）
|
機能設計書のドキュメント體系 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
前回までに表1の? 7「機能設計書」の基本設計ドキュメントとして、「表紙」「I/O関連図」「畫面レイアウト」「帳票レイアウト」について紹介しました。今回からは、詳細設計に関するドキュメントについて順に説明していきます。 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
"機能"単位での設計書 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
図1を見ると、「プロスペクト登録畫面」という機能は、畫面、イベント、BL（ビジネスロジック）などのオブジェクトから構成されていることがわかります。オブジェクト指向のアプリケーション構成においては、このように畫面やBLが単獨のオブジェクトとして存在します。 |
| 表紙 |
|
図2はDUNGEONの表紙です。一部では成果物を厚さで評価するという風潮もありますが、基本的に必要事項が記載されているなら、設計書のページ數は少ない方が読みやすいし取り扱いも楽です。そこで、表紙と更新履歴を1枚にまとめたフォーマットにしています。  図2：表紙と更新履歴 （畫像をクリックするとExcelファイルをダウンロードできます。/115.0KB） 表紙には、システム名、サブシステム名、機能名のほか、作成會社と擔當者を記入できるようにしています。これら基本的な記述專案については、プロジェクト単位で変更することも許可しています。たとえば小規模なプロジェクトであればサブシステム欄は不要となりますし、大規模なプロジェクトであればもう1階層サブシステムを用意する必要があるかもしれません。なお、設計書の作成日は、更新履歴の1行目に記載するということにしています。 |
| 更新履歴 |
|
更新履歴の記載メッシュは、設計書のバージョン／レビジョン管理の方針により異なります。ちょっとした変更があってもバージョン（レビジョン）を更新するのであれば、細かな更新履歴がたくさん記載されることになります。一方、ある程度の変更をまとめてレビジョンアップするのであれば、メッシュは粗くなります。DUNGEONでは、後者の方針に基づいて管理しており、ユーザ提出やレビューなどのタイミングにあわせて更新履歴を追加することにしています。 |
| 目次 |
|
図3は、DUNGEONの目次と概要です。上記と同じようにページ數を少なくするという理由で目次と概要を一緒にしていますが、分量が多ければ別ページにしてもかまいません。  図3：目次と概要 （畫像をクリックすると別ウィンドウに拡大図を表示します） 目次のポイントは、ページ番號の付記と記述專案の細かさです。目次をタイトルだけとするか、タイトルとページ番號を記載するかは、プロジェクトリーダーの裁量にまかせることにしています。 もちろんタイトルとページ番號を両方とも記載する方が読みやすいのですが、設計書は追記が多いのでその度にページ番號を振り直す必要があります（Wordなら、自動的に番號を振り直すように作成できるのですが…）。ユーザ提出まではタイトルのみとし、設計書が完成してユーザ提出時にページを記載するという運用が多いようです。 また、記述專案の細かさについても、プロジェクトリーダーの方針で決定します。テンプレートで用意されている大專案だけにするか、その下のサブ專案まできちんと記述するかは、目次作成・メンテナンスの手間と読みやすさのトレードオフとなります。 |
| 概要 |
|
「他人の書いた設計書はわかりにくい」とよく言います。いきなり規定フォーマットどおりに詳細仕様が大量記述されている設計書は、確かにわかりにくいものです。それは、設計者本人は暗黙の瞭解としていることでも、他の人にその前提がないからでしょう。時が経っている場合は、設計者自身でも自分で作成した設計書を理解するのに時間がかかります。 その原因の最たるところは、"概要"が記載されていないことです。この設計書で設計する"機能"がどういう目的のもので、誰がどう使うのか、そういう前提知識を最初に記載するだけで、ぐっとわかりやすくなります。そのため、DUNGEONでは、冒頭部分に"概要"を記載し、第三者が読んでも理解できる"わかりやすい設計書"を目指しています。 |
 |
|
各シートに最終更新日を付けるか 設計作業中は、かなりの頻度でちょこちょこ変更が入ります。通常、これらの変更をある程度まとめた段階でドキュメントがバージョンアップされ、表紙の変更履歴に記載されます。そのため、各シート上にも作成會社や擔當者のほかに変更日を記載し、そのシートの情報がいつ変更されたかをきちんと表す方式もよく取られています。 しかし、DUNGEONでは各シート上に変更日の欄は設けませんでした。これは、これまでの経験で欄を設けてもきちんと変更日をアップデートしない設計者が多かったためです。本來は、それを運用で徹底させるようなアプローチを取るべきなのでしょうが、その負荷と効果を天秤にかけて議論した結果、変更日欄を設ける代わりに、前バージョンからの変更箇所を青字で記述する方が実踐的と考えたのです。このように割り切るかどうかは、各社なりの方針があると思いますので、テンプレートを參考にする際は考えてみてください。 |
 |
| 專案説明書 |
|
前回、畫面／帳票レイアウトのサンプルと記入方法について説明しました。図4に示す「專案説明書」は、その畫面／帳票イメージと対になる設計シートです。基本設計フェーズで作成する「畫面／帳票レイアウト」は、基本的にユーザのイメージ確認を主目的としますが、その情報だけでは畫面を作成できません。そこで詳細設計フェーズで「專案説明書」を追加し、畫面や帳票の各專案について必要な情報を記載します。以下、主な記載專案について説明します。  図4：專案説明書 （畫像をクリックすると別ウィンドウに拡大図を表示します） |
| 專案名 |
|
畫面や帳票の專案名です。設計書に記載する專案名は、このようにわかりやすい日本語名で記載します。これらの「專案名」は、実際の畫面／帳票の「コントロール名」と対比します。この2つは、ER図におけるデータベース專案の論理名と物理名の関係に似ています。 DUNGEONの詳細設計書はプログラミング設計書ではないので、設計書上にコントロール名までは記載しません。コントロール名については、プログラミング規約を別途用意し、その中の命名規約に基づいてプログラマの裁量にまかせるという方針にしています。 |
| I/O |
|
各專案の入出力関係を表しています。前回、畫面レイアウトの説明で、6やOが表示、9やBが入（出）力というように記號で使い分ける方法を紹介しました。それとある程度重複する情報になりますが、ボタンやチェックボックスなどそれらの記號を使わないコントロールもありますので、專案一覧表でI/Oの區分を一元管理することにしています。 |
| 桁數 |
|
一般のコントロールにはMax Length、つまり最大桁數を規定するプロパティがあります。その設定値を設計者が定め、プログラマに通知します。畫面／帳票イメージでも、「ZZZ,ZZ6」や「BBBBBB」というように記載することで直感的に何桁かわかるようにしています。しかし、畫面幅の関係で見た目以上に入力できるように設定する場合もありますので、上記同様、專案一覧表で各專案の最大桁數を一元的に定義することにしています。 |
| IME（入力モード） |
|
入力專案に関しては、入力モードのOn/Offを定義します。擔當者コードなど半形英數字のみを入力する專案はOff、擔當者名など全形文字を入力する場合はOnを指定し、ユーザが切り替えなくても自動的にモード切替ができるようにします。 |
| 必須 |
|
入力專案で、なんらかの値が入力されないとエラーにする場合は必須欄に○を定義します。単純な必須チェック專案は○、條件により必須になるような場合は△として、備考欄または補足説明書に詳細を記述します。 |
| 參照 |
|
コードなどの入力を補助するためのコード検索（參照）機能の有無を定義します。ここでは、擔當者コードのようにポップアップウィンドウを開いてコード検索できるものはW、受注確度のようにプルダウンリストを開いて選択できるものをPという記號で使い分けしています。 |
| データ元（テーブル／列） |
|
畫面や帳票に表示される値が、どのテーブルのなんと言う列のデータであるかを定義します。 とは言っても、オブジェクト指向設計においては、テーブルの値を直接畫面に表すわけではありません。BL（ビジネスロジック）がデータをテーブルから取得し、それを畫面にセットするという中間的な役割を果たします。そのため、厳密にはBLのアウトプット変數と紐つけた記述とすべきなのですが、それだとかえって全體がわかりにくいので、ここでは根元のデータソースとなるテーブル／列を記述するようにしています。 |
| 値チェック |
|
入力專案については、必須チェック以外にも誤入力を避けるための値チェックを行います。たとえばコードがマスターテーブルに存在しているかどうかの存在チェック、日付や番號などの（自）≦（至）大小チェック、0と1以外は入力不可とするなどの値チェック、など專案に応じてどのようなチェックを行うかを定義します。 |
| 初期値 |
|
畫面ロードの際の初期値を設定する場合は、どのような値を初期値とするかを定義します。たとえば日付專案に今日の日付を初期セットしたり、金額欄に0をセットしたりするような処理を指示します。 |
| 備考 |
|
上記の規定欄で書ききれないことがらについては、備考欄に自由に記述します。フォーマットは1專案1行となっていますが、スペースが足りなければ複數行にして書くこともOKです。 |
| まとめ |
|
今回は、オブジェクト指向の要素を取り入れた機能設計書の構成について説明しました。基本設計書のドキュメントに対して、プログラマがこれを読んで作成できるためにいくつかの設計ドキュメントが追加されることになります。 その中から、第1弾として「表紙／更新履歴」「目次／概要」「專案説明書」の記述様式について説明しました。次回は、「イベント一覧」「BL一覧」「更新仕様書」「補足説明書」を紹介・説明し、詳細設計書の標準ドキュメント化を完了したいと思います。 |