読まないドキュメントより読めるコード

ウォータフォール開発はとにかく仕様書を書くことが求められる。文章を書くこと自体は嫌いでないが、仕様書を書くことは嫌いだ。なぜなら、意味がないからだ。その仕様書を他の人が読んで意思決定が行われたり、その仕様書をもとに他の人が開発をするなら、きちんとした仕様書を書かなければならない。しかし、自分がコーディングをするものの仕様書を書くことに何の意味があろうか。

読まないドキュメントを一生懸命書くより、読めるコードを書いた方がいい。

ソースコードが最も重要な仕様書だ。障害が起きたときに原因を調べるとしたら、当然ソースコードを読む。プログラムの動きを規定しているのはコードだからだ。ソースコードを読まずにプログラムの原理を調べるなんて不可能だ。一次情報・生データが最も重要だ。ソースコードを大切にしなくて、一体何を大切にする。何が三現主義だ。

仕様書ソースコードの整合性を保つことはできない。仮に仕様書が残っていたとして、それがソースコードの整合性がとれていることを一体だれが保証してくれるのか。ウォータフォール開発のV字モデルを考えたら、Vの後ろのほうの結合テストでバグが発見されたら、理想的にはVの対岸の機能設計に戻る。実際には戻らずにバグだけ直してしてVの先に突っ切って行く。機能設計の仕様書はそのままだ。判子を押してあるということは、変えるなということだ。開発プロセスからして、仕様書ソースコードの整合性を取ることは保証されていない。そんな仕様書が役に立つのであろうか。

f:id:fjkz:20150917222826p:plain

仕様書を書いている手間があるなら読めるコードを作ることに注力すべきだ。読めないコード――腐ってるとか臭いがするとかで表現されるコードを残されても困る。ソースコードが最も重要な生産物なのだから、これが汚いなんてありえない。最終成果物がゴミなら、一体何のためのプロセスなのか。機能追加も障害原因の究明も困難だ。そもそも汚く正しいコードを書けるほど頭のいい人間はいない。汚いコードはバグっていると考えるのが自然だ。プログラムの動きから読み取れない、書き手の意図はドキュメントでなくてコメントとして書いておくべきものだ。

仕様書を求めることは品質を落とす。完全にソースコードと整合性の取れた仕様書があって、美しく読みやすい品質の高いコードがあれば最良だ。しかし、人も時間も設備も潤沢でなかったらそれを求めるのは無理だ。品質の高いコードが欲しくて作っているのだから、優先順位を落とすべきはドキュメントの方だ。もっというと、品質の高いコードを書けるスキルの高い人に事細かな仕様書なんて作らせることは、その人の能力を殺す行為だ。

仕様書なんて作らせてたら、コードを読めない人・書けない人を量産する。読まなければ読めるようにならないし、書かなければ書けるようにならない。そうしたら読めないコードが再び生み出されていく。

過剰なドキュメントは害悪でしかない。

The Art of Readable Code (Theory in Practice)

The Art of Readable Code (Theory in Practice)