未来のいつか/hyoshiokの日記 このページをアンテナに追加 RSSフィード Twitter

2005-05-10 いろいろ

無駄なドキュメントは書くな

ひたすら実装に関するドキュメントをしこしこ書いている人がいるが、好きで書いているわけではなく、書かされているのかもしれないけれど、そーゆー無駄なドキュメントは書くな。時間の無駄である。実装は日々変化する。それに追従する形でドキュメントが更新されるということはない。断言する。実装に関するドキュメントと最新の実装は常に食い違っている。いまだかつて同期したことがない。無駄なドキュメントを書く時間があるならコードを洗練しろ。無駄なドキュメントを書く時間があるならコードをドキュメントにしろ。

ソフトウェア工学の教科書にドキュメントの重要性が書いてあるからといって信用してはいけない。ウオーターフォールモデルが商用ソフトウェア開発の現場で役にたたないように、実装に関する詳細ドキュメントは百害あって一利なしである。

コードがドキュメントだ。 http://capsctrl.que.jp/kdmsnr/wiki/bliki/?CodeAsDocumentation

http://groups.google.co.jp/group/fj.comp.oops/msg/b0df491f0d07a689?q=yoshioka%40best.com&start=50&hl=ja&lr=&rnum=52

今,手元に第2版を置いているのですけど,ドキュメントについては15章に書いてあると思うのですが,そこで「フローチャート呪い」ということで,その役割を否定しています.また「自己文書プログラム」ということでプログラムのコードの中に文書を入れる事を提案してます.

プログラム文書は悪名高いほどに貧弱で,そのメンテナンスはさらにひどい.プログラムの変更が,すみやかに正確にそしてそのまま紙の上に記述されることはない.”

”主要な目的は,文書作成の負担を最小化することだ.”

ブルックスの第2版では,漸増的構築モデルということで,マイクロソフトの「毎晩構築」アプローチを紹介してます.デイリービルドとかナイトリービルドとか呼ばれているやつですね.これは毎日毎日ビルドを繰り返して,徐々に機能を洗練しいくアプローチです.

毎日のビルドでは常に動くプロダクトが得られます.時として機能の後退(リグレッション)が発生しますが,毎日ビルドしてリグレッションテストを流していますからすぐに発見できます.いつ失敗してもいいのだけれどそれを発見してすぐに修正するというプロセスが組み込まれています.

このプロセスのダイナミズムを理解しないとなかなかシュリンクラップの現場の勢いを理解できないかなと思います.

一つのプロダクトが出荷されるまでにものによっては数百回,あるいはそれ以上ビルドされて,常に修正されるというイメージです.

http://web.archive.org/web/19990423145139/http://www.best.com/~yoshioka/d/98/i980227.html

とかも読め。

なお最新版は

みたいです。(出版社が変わっただけで内容は一緒だと思う。人月の神話)

fjの教祖様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種類の表示方式で言ってもらっても、同じバグが入っているのでは価値は無い。

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

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

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

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