業務システムの開発ドキュメント標準化 第４回：詳細設計書（前半）

機能設計書のドキュメント体系

   設計ドキュメント標準「DUNGEON」で定義されている設計工程のアウトプットは表1の通りです。「DUNGEON」では、基本設計書で骨組みを定義し、詳細設計書で肉付けを行います。つまり、基本設計書で作成したドキュメントはそのまま（必要に応じて修正も加えて）利用され、さらに詳細機能を表すためのドキュメントを追加して「詳細設計書」となります。

---

?

ドキュメント

用途・内容

基本
設計

詳細
設計

1

業務フロー

業務の流れを理解し、機能を洗い出す

○

 

2

機能一覧表

開発範囲となる機能（画面・帳票・バッチ）の一覧

○

 

3

ネットワーク構成図

システム構成を把握

○

 

4

テーブル定義

SI Object Browser 使用

○

 

5

ER図

SI Object Browser 使用

○

 

6

画面遷移図

画面遷移を図示

○

 

7

機能設計書

機能別の設計書

○

○

（表紙）

 

○

○

（目次／概要）

 

 

○

（I/O関連図）

データと機能の関係を図示

○

 

（画面レイアウト）

画面イメージ

○

 

（帳票レイアウト）

帳票イメージ

○

 

（フローチャート）

バッチ処理のフローチャート

 

○

（項目説明書）

画面／帳票の項目説明

 

○

（イベント一覧）

画面操作で発生するイベントの一覧

 

○

（BL一覧）

機能に含まれるBL（ビジネスロジック）の一覧

 

○

（更新仕様書）

機能またはBL単位の更新・処理内容を記述

 

○

（補足説明書）

上記の記述に対する補足説明

 

○

8

設計書記述様式

設計書の記述方法の説明

○

 

表1：基本設計および詳細設計フェーズのドキュメント

   前回までに表1の? 7「機能設計書」の基本設計ドキュメントとして、「表紙」「I/O関連図」「画面レイアウト」「帳票レイアウト」について紹介しました。今回からは、詳細設計に関するドキュメントについて順に説明していきます。

"機能"単位での設計書

   機能設計書は、機能単位でドキュメントが作成されます。例えば、「プロスペクト登録画面」と「プロスペクト一覧画面」と「プロスペクト一覧表」という3つの機能があれば、3セットの機能設計書を作ることになります。ここで注意して欲しいのは、設計書の記述はあくまでもユーザのイメージする"機能"単位で、プログラミング単位の"プロシージャ"や"クラス"ではないということです。この"機能"という概念について、図1「プロスペクト登録画面」を例に説明しましょう。

図1：プロスペクト登録機能の構成

   図1を見ると、「プロスペクト登録画面」という機能は、画面、イベント、BL（ビジネスロジック）などのオブジェクトから構成されていることがわかります。オブジェクト指向のアプリケーション構成においては、このように画面やBLが単独のオブジェクトとして存在します。

   画面「プロスペクト登録画面」を参照モードで開いたときにイベント「ページ.ロード」が発生し、イベント処理の中でBL「プロスペクト参照」が実行され、BLはイベントから与えられたパラメータ「プロスペクト番号」を使ってテーブル「プロスペクト基本」「プロスペクト詳細」などにアクセスし、そのSQLで得られた結果を画面に表示する、このようなアプリケーションの動作を定義するために、DUNGEONの設計書では、オブジェクト間の関連および各オブジェクトの処理内容をオブジェクト種類単位でわかりやすくまとめる様式にしています。

   以下、表1の? 7に含まれる各ドキュメントを順に説明していきましょう。

 

表紙
   図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一覧」「更新仕様書」「補足説明書」を紹介・説明し、詳細設計書の標準ドキュメント化を完了したいと思います。