詳細設計書ってどこまで書くの？

開発

今修正（というか書き直し）をしているプログラムの設計書を引っ張りだしてみたのですが、

  • 「何がほしいのか」が書いてないのに「どうやるのか」だけが詳しく書いてある
  • なのにその通りに実装すると目的が達成できない
  • そして、ソースコードを見てみるとそんなロジックになってはいない

という感じでした。他にも、SQLの箇所を見ると、

  • SQLなのかSQLじゃないのかよくわからない
  • 「条件」という項目に「列１＝'A' OR 列１＝'B'」と書いてあり、「それって、実装したら列１ IN ('A', 'B')になるよね」と思うようなところがある
  • 一方で、「対象テーブル」という項目がOracle独自構文のジョインで表現されている

前者の設計書は、そのまま実装できる設計書を書ける人があまりいないこと（自戒の意）を考えると、実装担当の人のためにあそびを持たせるべきだと思うのですが、後者の設計書は、日本語の項目名を英語の列名に直せばそのまま実装できるものを書いた方が良いと思います。詳細設計書ってどの程度まで実装丸出しにすべきなのでしょう？僕の場合は漠然と以下のように思っています。

  • 手続きは概要や戦略を書く
  • 「(1)現在のレコードをワーク領域に退避」みたいな実装上の都合は書かない
  • 「常に最小値を持つレコードと比較する」のようにどうなっていればよいかを書く
  • ツールで自動生成やコピペが効くレベルでなければ実装丸出しにしない

ほどよい抽象化をすることが段階的詳細化ということだと思うのですが、難しいですね。あと、設計書にも、詳細を記述するもの以外にそれらをまとめる役割をもつものがあるので、情報の二重化や乖離が悩ましいですね。