基本設計と詳細設計書、それぞれの設計書を書くときに意識すべきこと

アマチュアSEでもない限り、システム開発にていきなりプログラミングから始めるわけではありません。家を建てる大工さんも、建築士が用意した設計書に従って家を組み立てていくように、エンジニアも設計書をもとにしてプログラミングをしていきます。

そして設計という工程には、大きく分類すると基本設計と、詳細設計という二つのフェーズが存在します。基本設計と詳細設計、それぞれの設計書では、まず誰のために用意するのかという点が異なってきます。

この”誰のために”という、ターゲットをしっかりと理解していないと、本当に良い設計書を書くことはできませんので、ご注意ください。今回はシステム構築における設計書を書くべきときに意識するポイントについて、ご説明していきたいと思います。

基本設計はお客様でも容易に理解できること

まず基本設計を用意する際に大事なことは、システムに関しては知識のないお客様でも、容易に理解できる内容になっていることです。

システム構築とは、お客様と一緒になって進めていく共同作業のようなものです。そのため設計書はSEやPGだけが理解していればよいものではなく、お客様にも内容を把握してもらわなければなりません。どのような画面があり、どのような処理が行われて、どのような結果が返ってくるのか、こうしたことをお客様と共有するのが基本設計書の役割なのです。

画面イメージや、アウトプットとなる帳票やデータのイメージ、システムの処理フローなど、画像やイメージ図など、視覚的に理解できるものをふんだんに使うことで、よりお客様にも理解しやすい設計書ができあがります。

もちろんSEやPGにとっても基本設計書は大事ですが、システムに関して知識の乏しいお客様を意識して設計書を書くと、より良い内容になるはずです。

詳細設計はプログラマーにとって分かりやすく

お客様とシステムイメージを共有するために用意する基本設計に対して、詳細設計はプログラマーのために用意します。詳細設計は内部設計とも呼ばれることがあるように、基本設計で定義したシステム概要としての仕様を、どのようにしたら実現できるのか、機械的に形にしていくことができるのかを明記するのが詳細設計です。

必要モジュール、処理ロジック、用意する変数、SQL文など、プログラミングに必要な情報を記載していきます。そのため詳細設計は、お客様が目を通したところで、内容を理解することは難しいでしょう。情報処理に対する理解の深いプログラマーだからこそ理解できる内容になっているはずです。

よくできた詳細設計書というのは、プログラマーが頭を使うことなくコーディングしていけるほど、詳細にプログラム仕様が書き込まれていることです。逆に読み手によって解釈が分かれてしまうような、あいまいな記載のある詳細設計書は、質が低いと評価することができます。あいまいな記載が多いと、バグを生み出すことにもつながってしまいますので注意してください。

それぞれの設計書で整合性が取れることが大事

基本設計書と詳細設計書、それぞれで誰に説明することを前提として用意するのかは異なりますが、それぞれで内容が異なり、矛盾が生まれてしまうようではいけません。あくまで基本設計書で定義した仕様を、詳細設計書でプログラム仕様として落とし込むというルールは守ってください。

両設計書間では、必ず整合性が取れるようにしていきましょう。

項目のリンク番号は統一する

SEやPGであれば、基本設計書を確認し、どのような処理ロジックになるのかについて、詳細設計書で確認することがあります（その逆もまた然り）。

こうして設計書間を行ったり来たりする場合、各項目のリンク番号が統一されていることで、非常に読みやすくなります。例えば画面上の「決定ボタン」という項目には「B-1」といった番号を振り、その番号は基本設計と詳細設計で共通して利用するなど。

リンク番号は画面・モジュール・オブジェクトなど、さまざまな対象に対して有効です。設計書を書くには「自分だけが分かっていればよい」のではなく、自分以外のSEやPGにとっても読みやすくなる工夫を凝らしていきましょう。

 

おわりに

基本設計書は、お客様にとっても理解しやすい内容にまとめられていることが、良い設計書と言えます。また詳細設計書は、プログラマーが頭を使わなくてもコーディングできるレベルまで記載があると、良い設計書と言えます。

同じ設計書でもターゲットが違えば、良い設計書にするためのポイントも異なります。ただしあくまで同じシステムの設計書のため、それぞれで整合性が取れていることは絶対条件です。良い設計書を書きたいのなら、自分本位ではなく、読み手のことを考えて設計書を書くことを忘れないようにしてください。