Joel on Software

読んでます。19章(全45章)まで読みました。

5章からの仕様書について話を読んでいて、「プログラムが仕様書を書きたがらない理由は、仕様書が本質的にDRY原則に違反しているからではないか」と思いました。

ソースに書いてあることと、同じことがドキュメントにも書いてあるから。というのはもちろんあるのですが、それ以上に仕様書ではある物事を色々な側面から書く必要がどうしても出てくるからです。つまり、概要を書いたあとで、詳細を書く。すると、概要に書いたことが一部重複して、詳細にも書かれます。または、画面仕様の記述では画面イメージを載せて、さらに画面上のコンポーネントについて、表組みの一覧で記述したりします。すると、画面イメージ内と、一覧表の両方に「○○ボタン」が現れます。ボタンに表示する文字列を「OK」から「決定」に変えたければ両方を直さなければならなくなります。
このように、ソースをたった一行書き換えるだけのような修正でも、ドキュメントにはいたるところに影響が出たりします。なので、プログラマがいくらがんばってDRY原則やOpen Close原則に則った変更に強いプログラムを作り上げても、ドキュメントの方は変更に非常に弱いので、結局、ドキュメントと実装が一致していなくなったり、あるいは初めからどうとでも取れるあいまいな記述しか書かなかったりで、「そんならそんなものなくてもいいじゃん」と言う結論になってしまうのではないかと思います。

もちろん、これはドキュメントを書かなくても良い、または書かない方が良い理由にはなりませんが。