無駄な詳細設計書を滅亡させるための処方箋
昔は「詳細設計書なんてアホなもん作ってもプログラミングには何の役にも立たないんだよふぁっきゅー！」と言い続けるのが、詳細設計書を滅亡させる手段だと思っていたけど、どうも事態はそんな簡単じゃぁないっぽい。
じゃあ一体どうすればいいのかってのはマッタク思いもつかない。まぁカンタンに無くなるもんだったらとっくの昔に滅びてるわけだしねぇ……もし、解消することが出来たら、ないし処方箋を思いつくことができたら、いつか blog に書きたいです。
詳細設計書が滅亡しない理由 - kagamihogeのblog
SIerが作らされる詳細設計書（内部設計書とかプログラム設計書などと呼んだりもします）の評判は相変わらず悪いですね。このへんについては前からいろいろと考えてたことがあるので今回まとめてみます。コーディング時点で必要になる文書を極限まで減らしつつ、ウォーターフォール式の開発で納品物もきっちりそろえる、SIerのためのエクストリーム詳細設計書です。
※業務システムの開発を想定しています。組み込みやコンパイラ開発のようなプロジェクトでは事情が違うと思います。
1. コーディングが終わったら捨てる
そもそも詳細設計書は詳細設計の成果物だと思わない方が良いです。成果物はソースコードであり、詳細設計書はコーディング前の下書きだと割り切ると、何を書くべきか見えてくると思います。要は（詳細設計＋コーディング）の時間短縮に貢献する内容のみを書き記すのです。書かないほうが時間短縮になる内容であれば何も書きません。コーディングが終わったらもう見ないので体裁もこだわりません。
2. 必要な部分だけ書く
実装するクラスやロジックを網羅的に文書化していたらコーディング以上に時間がかかってしまいます。基本設計からコードに落とし込む前にワンクッションおいて明確にしておきたい部分があれば、そこだけ書くようにします。
（例）
・ポイントになる部分のシーケンス図
・ちょっと複雑な部分のオブジェクトの関連
・ユースケース（業務シナリオ）の細かい部分
3. コミュニケーション支援目的に使う
詳細設計書はチーム内で実装方針について意識あわせするためのコミュニケーションツールとして使います。だから、ホワイトボードのハードコピーだってかまいません。１人プロジェクトの場合も、１週間後の自分とコミュニケーションする備忘録のような目的で使います。
4. 詳細な詳細設計書（変な表現だな）がなければコーディングできないような素人をチームに入れない
プログラム１行ずつが日本語で書かれているような設計書は、プログラム学習用の教材としては効果がありますが、そんな余計な教材をシステム開発で作っている暇はいまやありません。逆に言うとそんな設計書がなければコーディングできないようなメンバーを現場に入れるべきではありません。
5. 詳細な詳細設計書がなければコーディングできないような言語・ミドルウェアを使わない
現代的な言語やミドルウェアを使うとロジックを高いレベルで抽象化できるため、やりたいことを素直に表現できます。アセンブラやCOBOLを使うのであれば詳細な設計書も必要ですが、極力そのようなことにならないようにしたいですね。
6. 詳細設計書から逸脱することを怖れない
前述のように詳細設計書は設計〜実装の下書きです。コーディングまでが本来の詳細設計と考えるべきです。なので詳細設計書の内容に不備があれば、怖れずにより良い別のロジックでコーディングします。コーディングの正しさはテストが保証してくれます。そしてまた詳細設計レビューもテストケースをレビューすべきなのです。
7. 納品用、保守用のドキュメントはソースコードから生成する
コーディングが終わったら詳細設計書は捨てると書きましたが、保守のためのドキュメントは必要です。そういったものはソースコードから生成すれば良いのです。javadoc、Doxygen、RDocのようなツールを使えば、注意深く目で追ってチェックしなくとも最新のソースコードに対応したドキュメントが作成できます。
テーブル仕様書も、CREATE TABLE文やDESCコマンドの出力をExcel文書にするようなちょっとしたプログラムを用意すれば簡単に作成できますね。
顧客側からしても、本当に必要なものは保守のためのドキュメントであり、決してページ数だけ多くて後から見ても役に立たない文書が欲しいわけではないはずです。なので、詳細設計の成果物としては保守に必要な内容のみを厳選して納品すべきです。
自分は元SIerですが今は社内SEで内製しています。ドキュメンテーションについてもいろいろ試行錯誤できる立場なので、これまで比較的うまくいった方法を元に少しSIer向けにアレンジしてみました。どうでしょうか。
