読者です 読者をやめる 読者になる 読者になる

methaneのブログ

このブログに乗せているサンプルコードはすべてNYSLです。

2種類の設計書

  • プログラムを書く前に書く設計書

これは、変更が発生することを前提に書くスケッチである。これを事後の資料として残してはいけない。また、この設計書を最新のソースと整合性を保とうとも思ってはいけない。手間をかけて綺麗に電子化しようとしてはいけない。このスケッチは、実装できた部分から捨てていくものである。
この設計書をレビューしてより良いものにするのは良いが、この時点で完全な設計を目指してはいけない。後戻り工数を怖がり、チェック工数を後戻り工数以上に増やしてはいけない。プログラミング言語自然言語よりもプログラムを簡単かつ正確に表現できる。プログラムを書くのは想像以上に工数が低い。(うそだと思うなら、数学の証明問題を、日本語と数式のどちらでするのが簡単・正確・早いか考えてみて)
ただし、プログラムを書いても、正しいかどうかの机上チェックが必要になると最初から判っている事に関しては、設計段階でチェックした方が良い。先にやるか後にやるかの違いなのでそのチェック工数はムダに増えた工数ではない。「やっぱりこの設計じゃ上手くいかないね」と実装前に判るか実装後にわかるかでは、前者が良い。

  • プログラムの後に書く設計書

これは、メンテナンスのための書類である。後でそのプログラムを読む人のために必要な事だけを書く。
プログラムを読めばすぐ判るような内容は書かない。メンテナが同じ内容を2度読むことになり無駄である。
プログラムを読むだけでは読み取れない外部使用や、読み取るのが難しい動的な部分を判りやすく残しておく。


これら以外の「設計書」と名づけられているドキュメントは、すべて証拠書類としてのドキュメントであり、生産性を伴わないムダなドキュメントである。無駄なドキュメントはたいがい後になっても読まれないか、読まれたとしても「なくてもいい」情報しか載っていない。こういったドキュメントの作成には、出来るだけ手をかけないようにしよう。