設計書についてあれこれ
発祥は浜口さんに贈るSI業界を良くする方法 - Hyper Great Creator やすを。旬が過ぎてしまった感があるので、ざっと思ったことだけ。
- プログラム設計書とは何か? ドキュメントには何を書くべきか? - プログラミング言語を作る日記が自分の考えに最も近いと思う。特に、↓の部分が。
ドキュメントには、以下のようなことを書くべきでしょう。
プログラム設計書とは何か? ドキュメントには何を書くべきか? - プログラミング言語を作る日記
- プログラムの概念や考え方を説明する。このようなことは、ソースだけでは説明しにくい。
- プログラムが「本来」どう動くべきかを定義する。あるプログラムの動きについて、それがバグであるのか使用であるのかは、ドキュメントで定義されていなくてはならない。
- プログラムの概念を表すものとして、デザパタをはじめとした各種パターンが有用。ただし、分からない（知らない）人にとっては単なる呪文にしか見えないので、周囲のレベルを把握した上で、使いどころを誤らないようにする。
- コードと1対1になるような詳細設計書が必要という人の言い分を聞くと、「プログラムがスパゲッティなので自然言語で書かれた詳細設計書がないと分からない」と。まずは、スパゲッティなのを直すべきでは…。以下、リファクタリングしたい病 - @ikikko のはてなダイアリーの辺の話に。
- スパゲッティを防ぐ別の手段として、コードレビューもいいね。ただ、今のプロジェクトはコードレビューがあまり重要視されていない。単体テストは、テスト結果のハードコピーを取って*1単体テスト仕様書と合わせた第三者レビューもあるのに何故？
- ちょっと考えて、自己完結。単体テストの結果が間違っているのはユーザに見える形でおかしいので直せとなるけど、ソースがスパゲッティでもユーザから見ても分からないからね。運用・保守担当者が死ねるけどｗ
