未来のいつか/hyoshiokの日記

fjの教祖様 2005/05/11 01:55 本当に?ドキュメントは無駄?
私に言わせると、「無駄なドキュメントを書いている」人は少ないが、「無駄にドキュメントを書いている」人は多い。つまり、内容が無く、読みづらく、基本概念がしっかりしておらず、いやそもそも何が言いたいんだかこれは…
というような「文字列」を吐く人は多い。
そしてそういう人のコードは汚く、場当たり的で、柔軟性に欠け、遅くて役立たずで、すぐ実態と乖離する。ついでに言うと、そういう人は図などの美的センスにも問題があるので、フローチャートも腐ったものでしかない。

ようするに原因と結果が逆なのではないかと思います。ドキュメントが無駄なのではなく、リテラシーがなってないだけだろう、と。無駄にドキュメントを書いているのではなく、無駄な文字列生成をしてそれをドキュメントと称しているだけだろう、と。「なぜそのコードになったのか」を説明するべきなのに、コードが何をしているのかの説明をするから、すぐ Out of date になるのだろう、と。

よいドキュメントを書く人は、全く違った視点から同じアルゴリズムを2度見つめます。ドキュメントとコードの2度、構造の理由を説明した版と実装を説明した版の2度です。で、ドキュメントを先にします。だから「良いコード」になります。もちろん、その後でコードにあわせてドキュメントを直します。ver1.0よりver2.0の方が良いに決まってますから。

下手なドキュメントを書く人は、先にコードを書きます。ver1.0です。で、それにあわせてドキュメントを書くので、ドキュメントもver1.0です。当然バギーです。すぐ変更がかかります。ドキュメントはver1.0のままで、役立たずです。

WebとかTangleとかが流行らなかったのは、まさにこの点がまざまざと出てきてしまうからではないかと。あれは「コードを説明する」システムであって、コードの意図を説明するドキュメント生成はできない。同じ事を2種類の表示方式で言ってもらっても、同じバグが入っているのでは価値は無い。

というわけで、ドキュメント害悪論は本末が転倒した結論だと思っています。

troubleantenna 2005/05/11 02:26 実装に関するドキュメントすべてが不要なのではありません。開発者には不要でも、利用者には必要なドキュメントがあります。分野にもよりますが「利用者が実装まで知らなくてよろしい」というのは開発者の勝手な思い込みであることが往々にしてあるものです。
よしおかさんは、もちろんそんなつもりでおっしゃっているのではないと思いますが、この手のドキュメント不要論はドキュメントを書けない人の自己正当化に都合よく利用されそうな気がして、どうにも好きになれないのです。。。

otsune 2005/05/11 19:47 この何年も前から続く定番の議論では、まず「ドキュメント」という広い意味を持つ言葉の定義を分解するところから展開してますよね。
そして最終的に「Howは可読性の高いソースで書く」「Whyは自然言語で書く」という感じの結論になることが多い気がします。

hyoshiok 2005/05/12 21:58 fjの教祖様さま、troubleantennaさま、otsuneさま、コメントありがとうございます。コメントのコメントはまた別途記させていただきます。(ごめんなさい)