詳細設計書の書き方について

Question

現場やプロジェクトによって詳細設計書の書き方は違ってくるとは思いますが、書き方のコツやアドバイスをお願いしたいです。

Answer 1

書き方のコツを3つ。書いたりレビューしたりしてきた経験から得たものです。
・主語・目的語・述語の主語と目的語が抜けないようにする
・段階的に詳細化する（3階層程度まで。複雑な内容は本文に注釈で別項に記述）
・上位や関連するの設計書の内容から名称や文章を引き継ぐ

それぞれ挙げた理由は以下の通り
・主語か目的語のどちらかがぬけると意図が伝わらない。
・全体の流れがわかると詳細の流れも理解しやすい。
・設計書が上下や横の関係が追えないものは読まれなくなる

よくやりがち（やられがち）な事例は以下の通り
・主語にあたる何が（誰が） や 目的語にあたる何に（誰に） が抜ける。後に解釈の間違いを起こす。
・詳細に書かれている部分の前後関係がわからずその内容が理解できない。
・設計書の中に今まで登場しなかった名称・呼称が登場し、それによって他の開発者が間違いを起こす。

このところは短期開発が主流で詳細設計書を成果物として求められないケースもあるのかなと思います。
ですが成果物として求められたものならば、できる限りきちんとしておきたいですね。
設計書はプログラミングのために書かれるものであるとういのが一般的な認識・常識ですが、
上位の設計を担当した人へのレビューや、テスト工程におけるテスト計画へのインプットになります。
「自分の正しく仕事をできたをプログラミング前に客観的に確認・賛同してもらうことのできる成果物」
なので、時代は変わりつつありますが、軽視せず取り組んでくださいね。

蛇足ですが、きちんとした詳細設計書を整えるというのは相応にコストがかかることです。
コストが成果物に対して見合わないというのも現実です。
また、詳細設計書をいくら整備しても、我々SEやプログラマというものはどこかで我流を行ってしまいます。
SEやプログラマでなくとも、普通は求められるものより書きたいことを書いてしまいがちです。
それら現実が積み重なり、結局はソースコードを追いかけ、デバッグをすることになります。
これは経験上防ぎきることはできないものだと思っています。

質問に対して残念ながらマイナス評価がついてしまいましたが、質問の内容は良いものだと思います。
顧客側にもシステム担当は居ます。そうした人物が見ても分かりうる設計書が後に役立ち評価されます。
3点コツとして書きましたが、ゆくゆくはSEやPGに対する評価向上になれば素敵ですね。

長文失礼しました。

Answer 2

詳細設計書に何を書くか、なんの目的で書くかによりますが、私は詳細設計書はいらない派です。
詳細設計書を実装方法を設計するために、フローチャートやSPDを書くのであれば、それにかけるコストをどこかで回収できるとはとても思えません。いきなりコーディングしたほうが効率が良いです。また、そうでなければ、プログラマとしてどこか間違っています。

---

誤解を招きそうなので追記です。
ドキュメンテーションが不要であると言っているわけではありません。機能仕様書は必ず必要です。つまり、実装の内容はソースコードに記載されているので、ドキュメントは不要ですが、プログラムの外部仕様は文章で明らかにしておく必要があります。 また、機能仕様書は操作説明書、運用手順書、インタフェース仕様書などで代用できるのが理想的です。ユーザに仕様を説明すること=ソフトウェアを設計することであるべきです。

一般的に詳細設計書と呼ばれているものは実装の内容を記載するものなので、それはドキュメントとして切り離さずにソースコードの可読性をあげることで不要となるように努力すべきだと思います。

Answer 3

階層化、オブジェクト化、ファイル分割など何かしらの部品に分割しますが、その分割単位でどの様な役割なのかを日本語で書いておくのが良いと思います。1人でコーディングしているうちは良いですが、他の人が触る時に違う機能を混ぜ込んでしまう事があります。

(すべての関数毎に役割を書くのはあまりお勧めしません、あくまで日本語で説明できる範囲内が良いです。「変数xxxが値正常値てある事をチェックする」と言ったコードを見たら分かる事は書く必要がありません。)

後は業界毎のルールに従う必要はあります。

Answer 4

私個人としては、いらないと思います。
（ソースのコメントやなんかで、要点まとめて後で見やすくしておけばとの前提ですが。）

ただし、大規模なものやお客さんに収めて継続して改造や改善をやるようなもの、
は作るようにしています。

どのようにまとめるかというと、
詳細なフローチャートなどは書かず、
全体の処理の概要的なものと、複雑な処理の部分は少し詳細までって感じ。
あくまでも後日不具合調査や改造検討する際に参考になるように。