【その8】詳細設計書論争
今から 4 年以上前に MBO に書いてしまった、新人ちゃん向けのメルマガが出てきた。
これで終わり！どんだけ新人ちゃんにインプットできたのかは分からんけど。
実は、メルマガとして記載していたのは前段部分のみで、後はパワポの資料に書いてたんよね。
さすがにパワポは引っこ抜けないから、ブログには全部平文で書いてるけど。
詳細設計書を作るかどうかについては、正直、いろんな会社のいろんなエンジニアに聞いてみたい。
このメルマガを書いた当初は詳細設計書必要派だったんだけど、今は迷ってる。
メリット / デメリットはもちろんあるけど、今の開発環境、開発スタイル等々によっても変わると思うの。
ノーコード / ローコードだとパラメーターシート（パラシ）が詳細設計書に相当すると思うし、
そもそも詳細設計書という概念が無いのかもしれない。
- 詳細設計書を作成するのかしないのか、
- 作成するとしたら、どんなものを作っているのか、
- 作成しないとしたら、品質担保はどのように顧客に説明しているのか、
- 普段、詳細設計書を作成しないけど、顧客の成果物に入っていた場合はどうするのか（少なくとも公共系は未だに求められているのは確認できてる）、
・・・
どれが良い / 悪いをジャッジしたいんじゃなく、純粋な興味から聞いてみたいものだわ。
※以下、当時の文章。
皆さんは詳細設計書って見たことありますか？
私はこの会社（※当時所属してた会社）に入って、2 プロジェクトしか見たことがありません。
基本設計書にがっつり記載しているから詳細設計書は不要、とか、工数に無いから、とか、そもそも詳細設計書を作る文化が無いから、とか・・・。
そういう声を聞いたりもします。
しかし、もし詳細設計書を書かなかった場合、どうやって単体テストを行うのでしょうか。
ウチの会社（※当時所属してた会社）は、ウォーターフォール開発モデルを標準としています。
上記に倣うと、詳細設計書の内容が単体テストの項目になるため、詳細設計書が無いと単体テストができないことになってしまいます。
今回は、詳細設計書を書くとしたら、何が・どんなことが必要となるか？を記載しました。
詳細設計とは
1）実装の前段階
実装の前段階で行われる場合は、内部設計や機能設計などで定義されたシステムの構造や仕様などをプログラム単位に分割し、各プログラムの動作を定義していく工程を意味することが多い。（≒プログラム設計）
2）プログラム設計の前段階
プログラム設計の前段階で行われる場合は、基本設計や概要設計で定められた機能や操作・表示方法などに基づいて、システムとしてそれをどう実現するかを具体的に定めていく。（≒内部設計）
→ ここでは、2）の意味とします。（ウチの会社ではプログラム設計書は記載しないため）
ウチの会社での詳細設計書
この会社で「詳細設計書」と呼ばれるドキュメントはほとんど見たことがありません。
この会社で詳細設計書を作成したのは、X 億以上の公共案件ぐらいでした。
（前職では必ず記載していたので、入社直後はカルチャーショックを受けました・・・）
＜詳細設計書が無い理由（たぶん）＞ ※私見です！
- そもそも作成する文化が無かった。
- 納品物に無いから作成しなかった。（業種、業界によって異なる部分があるため）
- 超大型案件以外は作成しない方針である。（工数の関係）
→ じゃあ、詳細設計書は作成しなくていい？
詳細設計書が無い場合
詳細設計書が無い場合、開発時には何とかなるかもしれませんが、保守開発時に新規メンバーが参画した場合、以下のことで困ることが多いです。（経験談）
- アプリケーション
- 基本設計書と実際のコードをひもづけるものが無いため、基本設計書を実装したコードファイルがどこにあるのか分からない。（物理名が分からない）
- 共通処理を使っている部分が見えにくい。何が共通処理となっているのか、どこで使われているのかは、ソースを Grep しないと分からない。
- ミドル・インフラ
- IIS の設定等、設定値の根拠が分からない。
- どこからどこにリダイレクト、リバースプロキシを行っているのかが分からない。
詳細設計書に欲しいもの
上記の内容を基に、詳細設計書に欲しい内容を以下に一例としてまとめました。
＜詳細設計書に記載してほしい内容＞
| 記載してほしい内容 | 概要 |
|---|---|
| ファイルの物理名と絶対パス | 基本設計書の内容がソース上のどこにあるかを記載します。 ひもづきを表す一覧を作成する方法もあります。 |
| 共通処理仕様 | 他の設計書同様、インプットとアウトプット、処理フローを記載した設計書を作成します。 |
| パラメーターシート（アプリ用） | インフラのパラメーターシートとは別に、アプリ側で設定した内容を記載します。 |
| リダイレクト・リバプロ仕様 | リダイレクト・リバプロ元、リダイレクト・リバプロ先を一覧にまとめます。 （他案件でも作成しています。基本設計書に持ってきているかも？） |
＜補足＞
※以下、私見です！！
上記の内容が全て基本設計書に含まれている、かつ、基本設計書の処理フローが詳細であれば、詳細設計書は不要な場合があるかもしれません。
今回で最後となります。
これで設計に強いエンジニアになれる・・・はず！
最後までお読みいただき、ありがとうございました。
