日本Rubyカンファレンス 臨時打ち上げ via オレンジニュース

テストコードにはWhat,
ソースコードにはHow,
そして，ドキュメントにはWhyを書くんだよ！

by 角谷さん

なるほどー。確かにそのとおり。でも、ソースコードにもつい Why を書いたりするし、ドキュメントにも How を書く。いや、やっぱドキュメントって難しい。ドキュメントに求められているものは、ドキュメントによって異なるから。そういう意味でも「ドキュメントの Why」はなかなか難しいかも。しかも Why に至るまでの Why ってのがあるし、それは文書化しにくいことも多い。