ドキュメント

「無駄なドキュメントは書くな」
http://d.hatena.ne.jp/hyoshiok/20050510#p1

とは言われるものの、では、どういうドキュメントが「無駄」なのか。それをはっきりさせないと、無駄なドキュメントは生成されつづける。

上記エントリには、 Martin Fowler氏の「コードがドキュメントだ」
http://capsctrl.que.jp/kdmsnr/wiki/bliki/?CodeAsDocumentation
がリンクされているが、何の前提もなく、『コードをソフトウェア システムにおける「（最）重要なドキュメント」と位置付け』ることは、誤解を招くだろう。

コードより重要なドキュメントがあって、それはそのコードの「仕様」についてのドキュメントである。

これについては、hyoshiok氏もFowler氏も解っているんだろうけど、読者によっては、「仕様」についてのドキュメントを書かなかったり、書いてもアップデートしたりしないでいいのだと思う者もいるかも知れない。

コードの「仕様」に次いで重要なドキュメントは、そのコードが仕様のどこに基づいていて、どのような詳細構造で書かれているかを示すドキュメントである。

「仕様のどこに基づくか」については、コードの頭にコメントで示すものだろう。

「どのような詳細構造で書かれているか」については、確かに、コードが最重要なドキュメントになるであろう。コードがその詳細構造そのものなのだから。

とすると、Fowler氏の言う「コードがドキュメントなら、プログラマがコードをクリアで読みやすくするよう努力することが重要となる。」とか「コードが読みにくいのは、コードのことを真剣にドキュメントとして扱ってないからじゃないだろうか」とかには同意できる。つまり、文章を書くようにコードを書けということだ。

文章を書くようにと考えると、「適切なパラグラフ別け」とか「章や項ごとのタイトル」なんかが重要となってくる。また、長いコードなら、長い文書と同じように「要旨」なんてのも解りやすさには重要だろう。

よくコードに空行いれない奴とか、教条的に行コメント禁止とか逆に行ごとのコメントいれる奴とかいるけど、それって、段落わけしない文章書くとか、タイトル付けないとか、一段落ごとにタイトル付ける奴みたいなものだよね。