会社で使うようになってきたので、まとめてみます。

プログラムのメンテナンスのため、また効率のよい分業のためには適切な文書化が必要です。二度手間を防ぐために、先に仕様を定めて文書化してから、実際のコーディングにかかるのが理想です。しかし仕様上の欠陥がみつかって大幅に変更になることもありますし、私の場合は経験が浅いのもあり細部の想定はコーディングを進めていかなければわからないことばかりです。なので結局後手にまわってしまうことが多いです。

なので、いかに短時間で手間をかけずにまとめるかにかかってくるわけです。そのためにソースコードレベルの仕様なら自動で作ってくれるツールが世の中にはあるのです。いくつか有名なところを挙げます

RDoc

Ruby専用ですが、たった一行のコマンドで綺麗なHTMLドキュメンテーションを生成してくれます。http://api.rubyonrails.org/ などはこれで生成されたページです。なによりも使い方が簡単なのが良いですね。

Doxygen

C/C++, Java, Python, Objective-C, C#などモダンなオブジェクト指向言語をサポートしていてかつ生成できる形式もHTML, man, LaTeXなど多彩です。Graphvizというツールを併用して構造図を作ることも定石のようです。

以上二つは特殊なコメントをつけることで生成する文書の装飾ができます。

GNU GLOBAL
これはどちらかといえば、仕様の文書化ではなくソースコードリーディングのためのツールです。ソースコードをマークアップして、変数名、関数名にリンクを貼り、定義部分と参照元を行き来できます。他人のコードをメンテナンスしなければならなくなった場合に有用かもしれません。(サンプルとして UNIXカーネルソースツアー！ なんてページも用意されてます。マークアップしたところでLinuxカーネルは巨大すぎますけど、4.3BSDあたりは知識があれば読めるような気がしてきますね。)

私も必要性を感じたのがごく最近のため、なにが広く使われているのか把握しているわけではありません。もっと有用なものがたくさんあるはずです。

また、最近読んだ本 にも書いてあったのですが、プログラミング言語というのは制御構造を記述する、まさしく”言語”に他ならないのだから、自然言語で置き換えるのはナンセンスで、書かれた時点でそのものが仕様になるのが筋だという言説もあります。つまりコードを美しく保つのも文書化の工程のひとつであるということですね。（だからといって仕様書が不要とまでは思いませんが。）

ミクロなアルゴリズムではコード＝仕様と言えるくらいわかりやすさを重視し、マクロな仕様ではより丁寧な文書を変更にしたがって随時用意することが大事なのだと思いました。