システム開発において、その後の工程をスムーズに進めるために非常に重要な「詳細設計書」。

開発工程において、基本設計で決定された内容をどのように実装するのかをまとめたドキュメントなのですが、どのようなものなのかイマイチ把握できていないという人は多いようです。

また、開発のスピードがあがるにつれ、Web開発の現場を中心に、「詳細設計書は不要だ」という意見が増えています。

この記事では、そんな詳細設計書について、それがどのようなドキュメントなのか、どんな情報が盛り込まれるのかを中心に解説します。

合わせて、詳細設計書がなぜ必要なのかと、詳細設計書を作成する際のポイントについても見ていきましょう。

詳細設計書とは

詳細設計書に盛り込む内容を解説する前に、まずは詳細設計書、ひいては「詳細設計」がどのようなものなのかを見ていきましょう。

詳細設計書の必要性についても、この項で解説します。

そもそも詳細設計とは

まず、システム開発は
「要件定義/設計/実装/動作テスト/納品」
という順番で行われます。

詳細設計は名前の通り、「要件定義」の次に当たる「設計」の工程で行われます。

詳細設計書とは、詳細設計の工程で決定されたことをまとめて、それ以降の工程に携わるエンジニアが参照するためのものです。

では、「詳細設計」とはどのような開発工程なのでしょうか。

詳細設計とは

ソフトウェアやシステムの開発において、前の工程で決定された仕様や要件定義について、詳細に決定することを「詳細設計」といいます。

開発工程の分け方によって、どの工程を詳細設計と呼ぶかが変わります。

一般的には、「プログラム設計」と「内部設計」のどちらかが詳細設計とほとんど同じ意味になります。

それぞれの工程について、次に解説します。

プログラム設計

プログラム設計は、工程としては、実装の前段階として行われます。

ここでは、前の工程で決定されたプログラムの構造や動作、仕様をプログラム単位に分割して、個々のプログラムで実現したい動作を明確にします。

内部設計

そして、内部設計はプログラム設計の前段階で行われます。

この工程では、基本設計で決定された、ソフトウェアやシステムの機能や操作方法などについて、それをどのように実現するのかを決定します。

個別のシステムが持つべき機能や、システム間の連携方法が詳細設計として定められます。

詳細設計書

詳細設計で決められた内容を盛り込んだものを、詳細設計書と呼びます。

さきほど見たように、詳細設計には、プログラム設計と内部設計のふたつがありました。

ですが、詳細設計書という場合、一般的には内部設計で決定された内容をまとめたものを指します。

詳細設計書は、その後の開発工程に携わるエンジニアやプログラマのために、「システムをどのように実装・実現するか」を事細かにまとめたドキュメントとなります。

詳細設計書の必要性

詳細設計書の必要性とは何でしょうか。

近年はWeb開発の現場を中心に、アジャイル開発と呼ばれるスピード重視の開発手法が採用されることが増えています。

こうした開発現場では、詳細設計書が軽視される傾向にあるようです。

詳細設計を行うためには、細かい仕様を決め、その情報をまとめる事が必要になるのですが、アジャイル開発の場合、
「開発を進めながら細かい仕様を決める」
という事も多々あります。

そのため、事前に設計書を完成させることが困難な事も理由の1つです。

その他、アジャイル開発が人気を集めている背景として
「開発納期が短くなっている」
という理由で、詳細設計書の作成に工数を出せなくなっているという理由もあります。

ですが、詳細設計書は、開発において非常に重要なものなのです。

詳細設計書をしっかりと作成しておかないと、要件定義やニーズ、仕様が不明瞭なまま開発が進んでしまい、機能が実現できないなど、現場に混乱が発生してしまいます。

小規模な開発であったり、特別にスピードが求められるなど、特殊な事情がない限り、詳細設計書は必要不可欠といえます。

例えば、現状動いている生産管理システムが国内と海外で別々のものを使用しており、それらを統合し、国内版のシステムに統合する依頼を受けたとします。

この場合、当然ですが海外の生産管理情報は、国内のデータベースに移行し、且つ過去のデータも参照できるようにしておく必要があるでしょう。

その時、アジャイルで移行作業を行っている最中に
「データベースの構造が違うから、単純な移行作業では移行できない」
となったとします。

そうなると、新規でテーブルの作成をしたり、そのデータを編集するための画面を開発する必要性が出てきます。

アジャイル開発では、こういった変更の際に大きな工数が必要となる可能性がある一方、きちんと詳細設計書を作成しておけば、事前に開発に必要な情報をまとめられています。

手直しも少なく、また開発に入る前に再見積もりするなど、トラブルの少ない開発が可能になるのです。

詳細設計書の記載内容

では、詳細設計書には、どのような情報を盛り込むべきなのでしょうか。

開発工程や開発するものによって細かな内容は異なりますが、ここでは、基本設計の次の工程で作成される詳細設計書について、一般的なトピックを紹介します。

変更履歴

詳細設計書は、開発が完了すれば役目を終えるわけではありません。

実際に運用が始まると、意外な部分でエラーになることも多いです。

その他、テストデータと本番データでは、データ量が桁違いだった結果、パフォーマンスが想定よりもかなり遅い・・・なども考えられます。

こういった時に、一旦完成した詳細設計書を修正する事があります。

そのため、「いつ」「だれが」「どこを」修正したのかを、履歴として保管しておく必要があるでしょう。

システムの概要

そのソフトウェアやシステムが何を目的として開発されるのか、そして、その目的を達成するために、どのような機能を実装するのかを明確にします。

このトピックには、開発で使用するツールとシステムの構成をまとめたコンポーネント図や、システムを構成するクラスをまとめたクラス図などが盛り込まれます。

外部インターフェース

システム間のデータ連携を担う外部インターフェースについての詳細設計書です。

ここでは、画面処理のルールや機能要件の定義、ユーザーインターフェースが持つべき機能などが記載されます。

外部システムとの連携が必要であれば、その連携方法もここで決定します。

例えば、APIを使って連携をする際には、必要な引数の数や内容、文字列や数字などの型の指定などがあります。

これらの情報をまとめておく必要があるでしょう。

内部インターフェース

内部インターフェースのトピックでは、システム構築に必要なDAO(Data Access Object)インターフェースについて、それぞれのインターフェースの役割だけでなく、論理名やメソッド名などのルールを記載します。

ここに記載されるDAOインターフェースには、共通のものから、マスター系、マスターテーブル以外に必要なテーブル用、表示用など、さまざまなインターフェースがあります。

プログラムの詳細

プログラムの詳細のトピックでは、使用するパッケージの名称と内容の説明を記載します。

クラスのフィールドや処理内容を、テンプレートを用いて整理しておくことで、実装の工程で混乱が生じることを防止します。

エラーチェック項目

入力画面の場合などでは、入力されたデータをチェックしていくわけですが、この時
・どのような項目をチェックするか
・どのようなメッセージを表示するか
といった事を定義する必要があります。

こういったエラーメッセージも詳細設計の段階で決めていきます。

その他の内容

ここまで紹介した以外のトピックとしては、メソッド実行の前後で任意の処理を行うインターセプターや、ユーティリティーのインターフェース、SQLについてのルールなどが、詳細設計書に盛り込まれます。

また、付録として、他の資料の参照や、システム使用時に留意するべき点などが記載されることもあります。

詳細設計書を作成する際のポイント

ここまで、詳細設計書とはなにか、詳細設計書に記載する内容についてみてきました。

実は、詳細設計書は、いくつかのポイントを守らないと、参照に時間がかかったり、かえって混乱を招いたりと、あまり役に立たないものになってしまいます。

この項では、詳細設計書を実際に作成するときに、気を付けるべきポイントについて解説します。

記載する範囲と精度を決めておく

基本設計書にはここまで、詳細設計書にはここまで記載するというように、それぞれのドキュメントの役割分担を明確にしておく必要があります。

そして、詳細設計書にあまり詳細な内容を記載してしまうと、その後の変更にかかる作業が膨大になってしまいます。

詳細設計書の精度についても、必要以上の細かさにならないように、あらかじめ決めておきましょう。

箇条書きなど、簡潔な表現をする

詳細設計書は、開発するシステムの目的や要件定義、仕様など、複雑な情報を扱うドキュメントです。

ひとつの文が長くなったり、冗長な表現が使われていたりすると、ドキュメントの視認性が落ちてしまい、情報の伝達がうまくいきません。

記載内容が長くなる場合は、箇条書きにしたり、トピックごとに細かく章立てをするなど、視認性を高める工夫をする必要があります。

また、主語と述語の関係がはっきりとわかるような文章を心がけましょう。

詳細設計書の章立ての方法

ドキュメントの視認性を高めるために、章立ては非常に重要です。

章の最初には、これから記載する内容について簡潔な説明(「この章では○○について記載する」など)を書きましょう。

そして、記載内容については、全体から詳細という形式をとりましょう。

この書き方をすることで、そのドキュメントを読む人にとって、全体像と詳細を把握しやすくなります。

章番号の表記についても、統一しておきましょう。

テンプレートを使用する

システムの仕様やプログラムの構成は、文章で説明するのが難しいことがほとんどです。

なので、詳細設計書を作成するときには、テンプレートを使用しましょう。

クラス図やアクティビティ図、シーケンス図、モジュール構成図など、記載内容によってさまざまなテンプレートがあります。

テンプレートを正しく使えば、複雑な記載内容を一目で読み取れるようなドキュメントを作ることができます。

事前にテンプレートの作成方法についてのルールを決めておきましょう。

用語の統一

ITの分野には、同じ意味でも複数の用語があるものが多いです。

同じものを指すのにバラバラな用語が使われていると、読み手は混乱します。

「この概念にはこの用語を使用する」とあらかじめ決定して、用語を統一する必要があります。

また、省略した用語を使用する場合は、その用語の初出時に「以下○○と表記する」と断わりを入れましょう。

ドキュメントの最後に用語集を掲載するのも効果的です。

加えて、「サーバー」と「サーバ」、「ユーザー」と「ユーザ」などの表記ゆれが無いようにしましょう。

変更履歴の記載方法を統一

詳細設計書の変更履歴、変更内容は、特に混乱が起きやすいところです。

変更履歴を記載するときには、あらかじめルールを決めておきましょう。

変更箇所を色分けするのならば、変更の時系列が伝わるように、そしてドキュメントの視認性を下げないために、いつまでの変更を明示するのかを明確にすると良いです。

さらに、変更の時系列についても、「YYYY/MM/DD」や「DD/MM/YYYY」「MM/DD/YYYYY」のように、表記が混在していると混乱を招くため、これについても事前に取り決めをしておく必要があります。

安心安全なシステム開発はAMELAに

今回は、システムの開発において非常に重要な「詳細設計書」について見てきました。

本文中でもお話したように、アジャイル開発が人気になると共に、軽視されがちな詳細設計書。

しかし、開発規模が大きくなったり、複数社が開発に関わる際には非常に重要になるのもまた事実でしょう。

きちんとした設計書の管理は、担当者が変わったとしてもその仕様を性格に判断することが出来ますし、追加開発もスムーズになります。

そのため、是非本記事を参考にして頂ければと思います。

現在、システム開発を検討されている企業様は、是非一度AMELAにご相談下さい。

様々な業界での開発実績があるからこそ、御社に最適な提案ができると存じています。