詳細設計書は必要なのか？

そもそも詳細設計書の役割は？

ソフトウェアの詳細設計書とは

ソフトウェアの詳細設計書とは、詳細設計を実施した成果物の文書です。
詳細設計に則って製造（プログラミング）を行うための指示書という位置付けです。
例えば、外注に製造を依頼する場合には、品質を保証するための指針として提示する資料となります。

なぜソフトウェアの詳細設計書は曖昧なのか？

ハードウェアの設計書は、誰が見ても同じ製造物を作ることが可能となるように、必ず解釈が一意になる具体的な記述をします。
なぜなら、ハードウェアは三次元的な実体を持つため、その設計書は数値が多用された図面として表現できるからといえます。

それに対して、ソフトウェア設計は、人によって解釈が異なる曖昧なものとなります。
なぜなら、実体を持たないものであるためであり、具体的数値を指定しない文章や抽象的な図表によってソフトウェアを表現しているからです。
そして、その設計書に対する「実装」方法は、ひとつだけではないからです。

ソフトウェアの詳細設計書は詳細に書けない？

詳細設計書は詳細に書き過ぎると役に立たない文書になってしまいます。
よくあるケースとして「ソースコードの内容を日本語で書き下したもの」がありますが、それが最善の実装方法でない限り、多くの場合にプログラマーの足かせになってしまいます。
そもそもソースコードの内容を書き下すくらいならば、ソースコードを記述したほうが効率的です。

詳細設計書という名のゴミ

これは、2012年に話題になったgm7add9.wordpress.com様の投稿タイトルです。
詳細設計書という名のゴミ
以下に引用させていただきます。

この業界で繰り返されるこの手の話は本当に根が深い。
いつも思うのだが、この議論の背景には必ず、プログラムを日本語で書いた「詳細設計書」がある。
彼らはあえて口にしない、あるいは気づいていないが、これには以下のおかしな前提がある。

 1. コードを書くことは基本的に設計を伴わない単純作業である。コードを書き始めるということは、設計が終わったということ。
 2. プログラマーは「詳細設計書」がないとコードが書けない。単純作業をするためのほとんど考えない人たちだからな。
 3. だから要件を理解している上流担当の人が、日本語でプログラムをかくための説明書を作ってあげる必要がある。それが詳細設計書だ。

設計者は、処理の流れをExcelで書く。まぁExcelで書くかどうかはここではどうでもいいのだが、とにかくExcel、それがルールだ。
で、入力情報はどこからどうやって持ってきて、どういう順番でどういう計算をして、監査記録をどこに残して
最後にどこにどういう結果を出力するか、とかを、小学生の読書感想文以上につまらない感じで淡々と書く。
愛とか感動とかそういう要素は一切ない。

～ 割愛 ～

しかし、だな。
俺からすると、どれだけ遠回りしてるんだあんたらは、って感じがしてならない。
そんな無駄な苦労するくらいなら、最初からコード書け、と。

～ 割愛 ～

もちろん、いきなり何でもかんでもコード書けっていっているわけではない。
ただ、コードが得意としている分野を、なぜにそれを最も不得手とする自然言語とExcelで無理してやろうとするのか、
そこが俺には全くもって解せない。
全プロジェクトメンバーの中で、一番スキルレベルの低い人に合わせて作業しているとしか俺には思えないんだが、
それは客から金もらって働くProfessionalな仕事の仕方なわけ?

それに、プログラミング能力のない人がプログラムの書き方を、Excelでプログラマに指南して、なんかいいことあるか?
しかも、なんで、同じことを日本語とJavaにわけて、2人で2回も書いてるのよ?
1人が1回Javaで書けばコスト半分だろ?
GDつかってコスト1/3ってあんたらちゃんとトータルコスト計算してるのかよ。

詳細設計書の問題点

Excel方眼紙（神Excel）というドキュメントのおかしさ

ソフトウェア業界では、なぜかExcelで仕様書やスケジュールを記述することが多く目につきます。
個人的な経験にすぎないのかもしれませんが、往々にして、そのプロジェクトは遅延していて、成果物品質はよろしくないことが多い印象です。
考えるに、Excelを利用している理由は「作成しやすい」であり、他人の「読みやすい/理解しやすい」を考慮していないことだと思います。

そもそもExcelは「表計算ソフト」です。
Excelは、根本的にドキュメントを記述することに向いていないアプリだと認識するべきです。

プログラミングパラダイムが意識されていないケースが多い

ソースコードを読めない、書けない人が設計した場合には、そもそもプログラミングパラダイムを理解していないケースがあります。
特定のプログラム言語であれば仕様書に沿って記述できるが、違うプログラム言語では仕様書の通りに記述できない場合があります。
例えば、COBOLのソースコードを見て記述した "詳細仕様書" をHaskellプログラマーに渡しても、"仕様書通り"には作成できないのです。

コーディング後に設計書が修正されるケースが多い

本来、設計書通りに作っても完成しない場合には、「設計書」が間違っているので、まず設計書を修正すべきです。
しかし現実にはそうではなく、先に、ソースコードを顧客の要望（本来的なあるべき仕様）に合わせる。
その後に、修正後のソースコードを元に仕様書が修正（または修正されることなくズレ・矛盾が生じたり）されます。
「実装」を元に修正される「設計書」に一体何の意味があるというのでしょうか？

【備考】コーディングシートという遺物

コーディングシートというのは、ソースコードの一行一行を紙に書いたものである。
かつてコンピュータを利用することが高価だった時代には、コンパイルするのにすら費用が必要でした。
紙の上で完璧なソースコードを作り上げて、それをコンピュータに取り込むという作業が最も効率的なプログラミングでした。
一人一台PCを配布される時代にとっては、無駄としか思えない作業です。

詳細設計書の書き方

ソフトウェアの詳細設計書はどこまで記述するべきか？

そもそも作成しない、という手段は有効だと思います。
実装中に表面化した問題点を都度ミーティングで解消していくほうが、効率的な開発が実施できる場合があります。

成果物のイメージが共有できていない場合には、UMLのクラス図、アクティビティ図を概要を抑えて記載した程度でよいと思います。
もちろん、どうしても説明が難しい箇所、環境問題を考慮して特殊な処理が必要な箇所というのは、注釈をつけたら上出来です。
ただし、そのようなことは実装中に発見できることであって、事前にわかることは稀です。

いっそのこと、開発担当者へどの程度の資料が欲しいのか聞くのが手っ取り早いです。
例えば、外注へ依頼した際に「処理概要は不要。入出力定義だけきちんと決めてもらえば作れる」といわれることもあります。
「コーディングシートのようなものがほしい」といわれたら、予算の無駄なので外注先を変えたほうが効率的な場合もあります。

プログラム作成後に詳細設計書を作成する

ソースコード完成後に詳細設計書を作成すると、矛盾なく正確で、運用・保守しやすいドキュメントになります。
クラス図およびクラス相関図は、Doxygenなどのドキュメンテーションツールを利用すれば、現在の実装と矛盾なく正確な資料を出力できます。
データの入出力については、テストコード自体が最も正しい詳細設計書になります。
開発Tipsなどの資料を添えて用意されていれば、その後のメンテナンスコストが大幅に減らせます。

関連ページ

• ソフトウェア設計