【ITエンジニア】（14）詳細設計について

詳細設計とは

詳細設計とは

ソフトウェアや情報システムの開発工程の一つで、全体の構成や行うべき処理の詳細など実装に必要な仕様を定義する工程。方法論の違いにより、この工程を機能設計、内部設計と呼ぶ場合もある。
詳細設計は基本設計と製造の中間に位置し、基本設計で定められた機能や操作・表示方法などに基づいて、プログラムやシステムとしてそれをどう実現するかを具体的に定めていく。
システムやソフトウェアをどのような構成にするか、それぞれの部分がどのような処理を行うべきか、それら部分間の連携・統合の方法などを決めることが多い。

V字モデルで考える

詳細設計を行う目的

製造工程の作業者に、システムの仕様を理解しやすくする
成果物を作成することで、単体テストのテストケースを抽出可能にする
成果物を作成することで、システムリリース後の保守作業を行いやすくする
製造工程で効率の良いコーディングを行うための参考になる
システムの要件や基本設計の不備を発見する

基本設計と詳細設計の違い

基本設計と詳細設計の大きな違いは、クライアントから見える部分を設計するか、見えない部分を設計するかという点です。

基本設計

基本設計は、システムの外側でユーザーやクライアントの目に触れる部分（インターフェース）、システム全体の概要、主な機能を設計します。
システムがユーザーにとって使いやすいかどうかを左右する部分になるため、クライアントのビジネスの結果に直接影響することもあります。
そのため、基本的に基本設計の内容は、クライアントの了解を得る必要があります。

また、クライアントの目に触れるハードウェア構成やシステム開発のスケジュール、費用などの管理も基本設計で決定します。

詳細設計

システムを開発するときに必要な部分やシステムの裏側（内部）でデータがどのように処理されているのかなど、ユーザーにもクライアントにも見えない部分を設計します。
そのため、詳細設計の結果にクライアントの了解を得る必要はほとんどなく、主にシステム開発の担当者やプログラミングを行うメンバー向けのものです。
プログラミングに必要な情報を設計し、メンバーが基本設計で決めた仕様を実装しやすいように表現する必要があります。

詳細設計の成果物

詳細設計の作成方法

詳細設計を作成する際のツールについて

詳細設計書を作成するツールは、現場により異なります。
自分で１から作成する際には好みのもので良いのですが、以下のような要件を満たすものが使いやすいと思います。

見出しつきの文書を作りやすい
オンラインで常に最新版を共有できる
図やチャートを挿入できる
変更履歴や変更差分を確認できる

DB設計の作成例

メッセージ一覧の作成例１

メッセージ一覧の作成例２

詳細設計書の作成例１

詳細設計書の作成例２

詳細設計書の作成例３

詳細設計書の作成例４（共通データチェッククラス）

詳細設計書の作成例４

詳細設計書の作成例５

詳細設計書を作成する際のポイントと注意点（1）

明確な記載を行う

詳細設計書（例1）の様に、自分が読んでも推測でしか作業を行えないような記載はNG。
具体的な物理名や名称を記載することで、なるべく推測をさせないような記載にするよう意識しなくてはならない。

プロジェクトで使用している用語を使用する

例えば、「関数」「メソッド」「ファンクション」「プロシージャ」というような用語は、同じような意味で使用されます。
そのため、プロジェクトが「関数」を使用しているのであれば、「関数」と記載したほうが良いでしょう。
プロジェクト用語集や設計書作成規約に定義されていれば良いのですが、ない場合は既存の記述内容に合わせたほうが無難です。

用語を統一する

例えば、「会員テーブル」を記載する時に、「会員情報」や「会員」や「会員情報テーブル」といった用語を複数記載してはいけません。
他者と記述が異なるのは仕方がないとしても、自分が記載した範囲であれば、一度「会員テーブル」と記載しなら、同じ意味の用語はすべて会員テーブル」と書くべきです。
統一されていないと、読み手としては「他にも似たようなテーブルがあるのかな？」と感じてしまいます。

詳細設計書を作成する際のポイントと注意点（2）

詳細設計書を記述している段階で実現方法を検討する

詳細設計書で記載した内容を、いざコーディングしようとした時に、実現困難な場合があります。
そのような実現困難なことが多発すると、コーディングの工数が増加していき、プロジェクト遅延発生の危険性があります。
現状の設計では実現が困難かもしれないけど、少し内容を変更しただけでコーディングが非常に楽になるようなケースもありえます。

条件分岐を記載する場合は記号を用いる

例えば、「詳細設計書例４（共通データチェッククラス）の LengthCheck」で、
「２．引数：入力データ >= 引数：最小値、かつ、引数：入力データ <= 引数：最大値であるかを
チェックする。」という記述があります。
この記述が「２．引数：入力データが引数：最小値以上である、かつ、引数：入力データが引数：最大値以下であるかをチェックする。」という記述だったら、いかがでしょうか。

コーディングを作成する際に「>=」しなければならない所を「>」と記述してしまう人が出てくるかもしれません。
もちろん、前者のように書いていても「>」とコーディングをしてしまう人はいますが、記号で読ませることにより、「>」と書いてしまう可能性を減らすことが出来るのです。

詳細設計について

何度も言いますが、詳細設計書の記述レベル／記述方法などは、会社／プロジェクト／人／言語／システム種別によって異なります。
成果物の種類も異なります。「詳細設計書などいらない」という意見もあります。

私も、「詳細設計書は正直不要なのではないか？」と思ってしまうようなことがあります。

なぜなら、修正作業が大変なのです。
一度作成した設計書を、コーディング時に修正があったからといって、再度修正するのは億劫です。

また、経験を積んでくると、基本設計書やシステムの話を聞いただけである程度の処理があるべき姿でイメージ出来たりしますので、「わざわざ設計書など書く時間があるのであれば、コーディングをさっさと進めた方が良い。どうせ、設計段階では間違いだらけで製造工程で変わるのだから。」
と思ってしまったりします。そのため、「詳細設計書などいらない」という人の気持ちもわかります。

しかし、プロジェクトの新規参画者や保守工程の作業のことを考えたり、大規模プロジェクトになってくると話は変わります。やはり、詳細設計書があると、助かると思える場面も沢山あるのです。
ただし、詳細設計書がしっかりとした形で残されている場合に限ります。

コーディングと異なるような詳細設計書や、何を言いたいのかわからない詳細設計書では不要と感じます。詳細設計書を作る場合は、製造工程以降に大きな修正があるという前提で、期間や工数を確保してくれていると良いなとも思います。