詳細設計書って何をどう書くの？

WEBアプリ開発のプロジェクトで詳細設計書を一から作成することになったので、
これを機に「詳細設計書に必要な最低限の記載内容」の再確認とメモ書きφ(..)
また別プロジェクトで一から書くことになった時の判断基準にするためにも。

本題に入る前に、前提知識をザックリと。

詳細設計書は、上流工程の
「要件定義」
クライアントの要望とその要望をどのように叶えるのかを明確にする。
↓
「外部設計」
要件定義で決まった内容をもとに、画面や帳票、操作性などのユーザーインターフェースを設計する。
外部システムと連携する部分の仕様を設計し、内部設計の土台を作る。
↓
「内部設計」
外部設計で決まった内容をもとに、システムとして何を使ってどう実現していくかを具体的に定めていく。←★ここの工程で必要になる設計書

一先ず、

・外部設計で作成する「基本設計書」はどちらかというとクライアント向けの設計書。
・内部設計で作成する「詳細設計書」はどちらかというと開発者向けの設計書。

という考えを念頭に置いておくと、どちらに書くべきかの判断基準にはなるかと。

以上を踏まえて、下記の条件で「詳細設計書に必要な最低限の記載内容」をまとめ。

～この記事が活かせる条件～
・開発手法がウォーターフォールモデルであること
・Javaフレームワークを使ったWEBアプリ開発であること

詳細設計書に書くべき必要最低限の項目

1.プログラム概要

1.1.概要

何のためのシステムで、それを実現するためにどんな機能を持っているのかをシステム概要図と共にザックリ記載。

【コンポーネント構成】

開発で使用するソフトウェア等の一覧とシステムがどのように積まれているかの構成図を記載する。

【機能構成】

開発するシステムの機能一覧と説明を記載。

【論理ER図】

DBテーブルとテーブル同士の関連を論理モデル(日本語)で図に表したもの。

※外部設計書に記載し、引用とするケースもある。

1.2.外部インタフェース

【画面インタフェース(UI)】

各画面の「ルール(定義)」「機能概要」「処理フロー」必要に応じて特記事項(＝使用可能記号一覧とか特殊漢字とか)など、ユーザインタフェース機能についてを記載。
※外部設計書に記載し、引用とするケースもある。

【外部システムインタフェース】

システム実現にあたり、外部の別システムとのやり取りが生じる場合、対象の外部システムとの通信手段などを記載。

【メールインタフェース】

システムにEメール通知などの機能が含まれる場合、Eメール本文のレイアウトなどを記載。
※外部設計書に記載し、引用とするケースもある。

【DBインタフェース】

DBへの接続方法、使用するテーブルやビューの一覧を記載。

1.3.規約等

【コーディング規約】

コーディングをする上での共通ルールを記載。

【ログ規約】

ログの出力レベル、出力方法、出力フォーマットについて記載。

【その他規約】

その他、使用するフレームワーク、ライブラリなどがある場合は独自の規約を記載。

2.内部インタフェース

2.1.DAOインタフェース

使用する各種DAOインタフェースについての説明を記載。※インタフェース＝部品

【共通DAOインタフェース】

あちこちで同じアクセス処理が生じる場合は、共通のDAOクラスを用意する。
上記のDAOクラスに共通するインタフェースについて記載する。

・論理名
・メソッド名
・INPUT（何を使って）
・OUTPUT（何を取得するのか）

因みに、共通DAOクラスの生成は「O/Rマッパー」を使用することが多い。

※O/Rマッパー
JDBCのAPIを直接使用する従来の開発方法で、データベースを扱う際に生じる複雑な処理をまるっと一まとめにしたもの。使用する開発言語とリレーショナルデータベースの非互換なデータを変換し、マッピングだけで対応できるようにしてくれる。

【マスタ系DAOインタフェース】

各種マスタDAOのクラス名と役割を記載。
マスタなので基本的には追加のインタフェースを定義しないが、必要に応じて追加したマスタDAOクラスのメソッドを記載する。

【テーブル用DAOインタフェース】

マスタテーブル以外の必要なテーブルのDAOについて「何をするために使うDAOなのか」を記載。

・論理名
・メソッド名
・INPUT
・OUTPUT

【ビュー用DAOインタフェース】

検索結果などの表示にビューを使用する場合に記載。

・論理名
・メソッド名
・INPUT
・OUTPUT

その他追加した外部システムのモジュールに応じて必要なインタフェースを記載。

2.2.インターセプター

メソッドにアノテーションとして付与するインターセプターについて記載する。

・論理名
・アノテーション名
・適用場所
・概要(何に使うアノテーションなのか)
※使用するフレームワークの仕様に準ずる

2.3.ユーティリティ

共通ユーティリティのインターフェースについて記載。

・論理名
・クラス名
・機能概要

例えば、複数箇所で同一のエラーメッセージを使用する場合、同じエラーメッセージを何個も記載するのは億劫なので、各エラーメッセージにIDを付与したものを包括した、MessageUtilクラスを用意する。
これは共通ユーティリティ対象となる。

3.プログラム詳細

3.1.概要

【パッケージ一覧】

各機能で使用するパッケージと説明一覧を記載。

【画面一覧】

画面名とURLの一覧を記載。

3.2.各機能の内部設計詳細

【html】

※使用するフレームワークの仕様によりhtmlの形式が変わることもある。

・クラス図
・クラス一覧

【MBean】

・MBeanクラスの主なフィールド

・MBeanクラスの主なメソッド

メソッドの処理内容を処理の流れに沿って記載。

【Logic】

LogicもMBean同様、Logicクラスで行う処理内容を処理の流れに沿って記載。

【DTO】

各処理実行時に必要なDTOの一覧と説明を記載。

4.SQLクエリ一覧

・使用するテーブルとSQL名の一覧
・各DAOクラスの実行に必要なメソッド名(SQL名)のSQL文を記載。
・SELECTする場合は実行パラメータ(論理名、物理名、型)も記載する。

5.付録

上記項目内で、「外部設計書に記載し、引用とするケースもある。」と記載したものが主に付録の対象となるケースが多い。
例として、システム内で表示する各メッセージにエラーコードNo.を付与し、一覧にしたものをメッセージ一覧として付録の扱いにする等。

6.設定項目一覧

システムの使用にあたり、システムプロパティやDB設定などで必要な設定項目と設定値、設定方法などを記載。

おわりに

ざざざっと。
今後、また一から書くことになった時に粒度の判断基準にするためにってのと、同じ様に迷った人にも何かしらのヒントになったらいいなと思い書き留めてみました。（かなり自分用に偏ってはいますが。）
正直、開発規模やプロジェクトの方針、ルール、見積もりによって粒度も仕様も全然変わるので、それを念頭に、「最低限これだけのことは記載しておいた方が良いんだなー。」くらいに留めておけばOKだと思います。
ご参考までに。

※今後も気づきがあったらブラッシュアップしていく予定です( ˇωˇ )