よしおかさんの「無駄なドキュメントは書くな」から。
ひたすら実装に関するドキュメントをしこしこ書いている人がいるが、好きで書いているわけではなく、書かされているのかもしれないけれど、そーゆー無駄なドキュメントは書くな。時間の無駄である。実装は日々変化する。それに追従する形でドキュメントが更新されるということはない。
まつもとさんも「オブジェクト指向スクリプト言語 Ruby」で「ソースがドキュメントだ。 バグも完全に記述されている」と言っている。
このドキュメントこそが成果物という悪習はウォーターフォール型の開発手法による部分は非常に大きい。なんせ要件定義やら設計やらのPhaseを終わらせようと思ったら、そのPhaseごとの成果物を納品する必要があるのだ。そりゃ、メンテも放置され、コードとの乖離は進む一方になる。しかも、たいていプロジェクトが後々きつくなるのは分かっているから、早いPhaseをなるべくさっさと終わらせたくてドキュメント自体の質も悪くなる。
なんでこんな状況が放置されているかについては、業務アプリケーション業界のストラテジスト不在という構造的な欠陥があったりすると思っているのだけど、この話は別でエントリをするつもり。
で、書きたかったことがコメント欄に指摘されていたので引用しておく。
「なぜそのコードになったのか」を説明するべきなのに、コードが何をしているのかの説明をするから、すぐ Out of date になるのだろう、と。
よいドキュメントを書く人は、全く違った視点から同じアルゴリズムを2度見つめます。ドキュメントとコードの2度、構造の理由を説明した版と実装を説明した版の2度です。で、ドキュメントを先にします。だから「良いコード」になります。もちろん、その後でコードにあわせてドキュメントを直します。ver1.0よりver2.0の方が良いに決まってますから。
下手なドキュメントを書く人は、先にコードを書きます。ver1.0です。で、それにあわせてドキュメントを書くので、ドキュメントもver1.0です。当然バギーです。すぐ変更がかかります。ドキュメントはver1.0のままで、役立たずです。
ドキュメントとコードのどちらを先に起こすべきかについては、ちょっと異論があったりするのだけど、大事な部分は全面的に賛成。
ドキュメントは実装の詳細ではなくて、なぜそのコードをそういった形で書いているのかという設計の思想を語るものであるべきだ。業務アプリケーションであれば、どのように顧客の業務を理解し、設計へと落としたのかというものだ。何をプログラムを起こすときのルールとしているのかと言っても良い。
コードはそのルールに沿って書かれる。保守の段階で、設計時の思想を理解できない人がコードを読むことは往々にしてある。そのときに的外れな変更をしないためには、そのプログラムの根底に流れるルールを理解している必要がある。
ちなみに、「コードがドキュメント」を口先だけでなく実践している人は、たいていこの「構造の理由」についてもヘッダ辺りに必要最小限のコメントがあるので、この問題もクリアされるような気はする。
そして、口先だけで「コードがドキュメント」を言い放つ人は、「コードくらいしかドキュメントと呼べるものがない」だけだったりするのは周知の事実。
念のためだが、このよしおかさんの話は「ひたすら実装に関するドキュメントをしこしこ書いている」ことが問題であって、なんでもかんでもドキュメントは書くな、コードを見ろって言っているわけではないと思う。あくまで、タイトルのとおり「無駄なドキュメントは書くな」なのだ。
