ドキュメントとしての詳細設計書と、プロセスとしての詳細設計

「ソフトウェアの「詳細設計書」とはなんなのか」というブログ記事を読んで考えたこと。設計に関するプロセスとドキュメンテーションの関係性についての考えの整理。SI屋的な視点で。

2024/8/18追記：文中にあった雑な文系disが不愉快というご指摘を受けました。ご指摘の通りだと思いましたので訂正しています。大変失礼しました。

「詳細設計書」とはなんなのか

nowokay.hatenablog.com

こちらの記事では詳細設計書とは以下のようなものであると整理されている。

• 表現を変えたコーディング（の一種）
• 机上プロトタイプ（の一種）
• 分析資料
• 保守（のための）資料
• （水平作業の場合の）作業指示書
• （委託している場合の）契約資料

上記以外で考えられるのは次のようなものがあるだろう

• 利害関係者が要求している
  • たとえば受託開発において発注者が要求している場合
  • ほかには連携している相手先システム側から要求される場合
• 品質担保のためのレビューのため
  • 非プログラマー（例えばCOBOもとい別言語で開発された既存システムの有識者）にレビューしてもらいたい等
  • 他にも有識者が希少なリソースなのでコード全部読んでくれとは言えない場合もある

このあたりは以前に以下のような記事を書いていた

• 開発者向けのソフトウェア設計書は必要か？ - 勘と経験と読経

逆に言えば、上記のいずれにも該当しない場合は設計書を作成する必要はないし、受託開発で発注者が要求しているだけの場合はコストとバーターで作成を回避する交渉も可能だろう。納入しても読まれないんだったら無駄だし。

要は詳細設計書は必要だったら（必要な範囲についてのみ）作ればいいし、不要だったら作らなくても良いのだ。ただし、ここには落とし穴がある。

詳細設計とはなんなのか

詳細設計書は不要と書いたが、プロセスとしての詳細設計（もしくは単なる「設計」）は省略できない。
ソフトウェア開発についてわかっていない初心者PMがやらかしがちなミスは「コスト削減のために詳細設計書の作成を不要として、設計する時間が不足するくらいにスケジュールを短縮してしまう」ことである。この場合はだいたいうまくいかない。

設計書を作ろうと作るまいとプログラミングをする上で設計は必要で、削減できるのは（時に珍妙なExcel方眼紙に）設計結果をアウトプットする時間だけなのだ。

では（アウトプットすることは別にして）詳細設計では何をやるのだろうか。
いろいろな表現があるだろうが、要求仕様を分析し、非機能要件（〇〇性）を満たしたプログラムの構造を検討するということになるだろう。

偶然いま読んでいる「ソフトウェアアーキテクチャメトリクス ―アーキテクチャ品質を改善する10のアドバイス」だと以下のような特性が列挙されていたが、設計時間を短縮しすぎるとだいたい犠牲になるやつだと思った。結果として品質が下がるのだ。

• モジュール性
• 凝集性
• 関心事の分離
• 抽象化・情報隠蔽
• 結合度
• テスト容易性
• デプロイ容易性

ソフトウェアアーキテクチャメトリクス ―アーキテクチャ品質を改善する10のアドバイス、3章　進化的アーキテクチャ：テスト容易性とデプロイ可能性でアーキテクチャを導く　より抜粋

ソフトウェアアーキテクチャメトリクス ―アーキテクチャ品質を改善する10のアドバイス

というわけで、詳細設計書は別として、詳細設計は必要だと考えている