コメントはドキュメントに取って代われるか

答え書かれちゃってるけど、私はその答えに否と答えたい。
理由
そもそもドキュメントが必要な理由は何か。後からメンテナンスする事を容易にするため。長く更新されていないドキュメントよりも手短なちゃんと現実に即したコメントの方が何十倍も価値がある。もちろんこの意見にも色々反論が出るだろうけど、「なんかこれ仕様どおりには動かないんですけど……」「あ、それ変更されてるから、××を××しないと動かないよ」みたいな会話、よく聞かない？それじゃ意味ないでしょ。という程度の事に受け取ってくださいな。
そして、リキ入れて図とか表とか沢山入れて作った仕様書には、まず間違いが発生しているという事。そしてその手の仕様書は更新されない事。時代が移ればツールも変わる。特に会社指定のツールじゃなければ、改修者が変わればツールも違う。下手をすれば、ドキュメントをちゃんと印刷できないなんて事態もあり得る。そんなのダメだと思うよ。
じゃ、コメントはどうかと言えば、読めなくなるという事はほぼ100%あり得ないし、コードが削られる時はコメントも削られる。ドキュメント更新が面倒な人でも、コメント更新は自分のためにもするかもしれない。読みやすいソースを目指している人は、例えばデータ構造なんかも、見やすく整形してくれていたりするし、「ソースがドキュメント」というのはあながち間違いではない事も多い。
しかしながら、その秀逸なソース品質を誰もが実現できる訳はないので、会社としては仕様書を要求してくる訳で。
それに、僕が言う「コメントがドキュメント足りうる」というのは詳細設計仕様書レベルであって、概要仕様書や、機能仕様書といった類い、そして、システム設計仕様書の様なグローバルな視点が必要なものは対象としていない。それらは「当然に」ぺーパーレベルで存在する必要があると思う。
そして、価値のあるコメントを書ける人は多くない気もする。その時に自分のコーディングやデバッグに必要なメモとして書かれるコメントは、ドキュメントの価値はありません。かといって、ソースを前後1行づつ計3行読めば判ることをコメントに書くのも無意味どころか罪。意味のあるコメント、そして必要充分なコメントというのは、非常に難しいものだとも感じている。
そしてソースコードそのもの。ローカル変数名なんかはみんな気にしないけれども、それこそちゃんとした名前をつければドキュメントとしての価値があるはず。ただ i とか、vec とかな名前は許さん。