詳細設計書に何を書くべきか

システム開発の工程では必ずと言っていいほど「設計書の作成」があります。

色々な種類の「設計」があるとは思いますが、一般的には「基本設計書」と「詳細設計書」ではないでしょうか。

そして「詳細設計書」にはいつも悩まされます。
どんなことを書くべきか。

なお、ここではアプリケーションの開発、特にビジネスロジック周辺の開発を想定しています。

私の経験でいうと

がありました。

このうち「ロジックを文章にしたもの」の割合が最も多かったのですが「これって意味あるの？」っていつも思ってました。

ロジックはコーディングしながら作り上げていくものだし、文章を書いている時点では正しいかわかりません。

多くのプロジェクトでは「設計書作成→実装」のプロセスを踏むので、結局「設計書作成→実装→設計書修正」みたいなことになります。
「工数が余計にかかる」し「メンテナンス」も追い付きません。

じゃあ本来何を書くべきか、どんな内容があればいいのか考えてみました。

プログラマーがプログラミングするためのドキュメント。プログラミングをするために必要な仕様、処理ロジック、SQL、変数などを記載する。

上記は一例です。ちょっと古すぎかも。
ただ「プロぐラミイングをするための」っていうところは今もブレてないと思います。

個人的には

がわかればいいのではと考えています。ちょっと外部仕様的な観点も入っちゃっているかな。

書いてあることしかできないPGは厳しいのかもしれませんね。オフショアとかでやる場合とか。

システムは作り終えたら「もう触りません」ということはほぼないと思います。

障害対応なり、機能追加なり、コードは常に変更する可能性があります。
それも特定のメンバではなく誰が変更することになるかわかりません。

そう考えると新規開発だけでなく、障害対応・機能追加の時も約に立つ設計書であるべきではないでしょうか。
分かりづらい設計書だと、結局コードを読むしかない状態に陥ります。

いや、それはある意味正しいと思います。ロジックの隅々まで表現するのは難しいので。

だからこそ「コードを読む」ための助けにもなってほしいのです。

基本設計書がきちっとある前提ではありますが、詳細設計書は上記のような内容でもいいのかなと考えました。

自分の苦手な工程なので、かなり主観が入っていますが(^_^;)

SE２号