私はコードにコメントを書かない。それは面倒だとか、ここに書いてある事情があるとかではなくて、「信念」として書かない。書くべきではないと思っているからだ。コメントを書いたら負けだとさえ思っている。これはもう20年来そうだ。
ちょっとしたメモのようなコメントは、つい書きたくなる。私は「自分のコードは他人も見る」「過去の自分は他人」と思っているので、その時の助けになるようなコメントはむしろ入れたい欲求にかられる。コメントで意思伝達しておけば楽だと思う。が、「コメントを書いたら負け」だと思っているから書かない。
例外的に書くのは、
- ファイルの冒頭に書くGNUなヘッダ
- ヘッダファイルに書く構造体の宣言
- コメントアウト
くらいで(これらはむしろ積極的に書く)、その書かないっぷりは、gotoよりも少ないくらいだ。
なんでそこまでコメントを嫌うかと言えば、
- コメントは嘘がつけるし、コンパイルエラーは出ない
- コメントに頼るコードにするのが間違い
- コメントに頼る奴はそもそも読むな
という理由からだ。
一番大きいのは、「コメントで嘘をついても何のエラーにもならない」ということだ。コメントの嘘で泣かされた経験のある人の数は、多分コードを読んだことのある人の数と等しいと思われる。
コメントで嘘をついてもエラーにならないから、コメントはメンテされない。また、騙された経験のある人は、そもそもコメントを信用しなかったりする。それでもコードの上で場所を取り、こちらに「読んで！」と語りかけて来る。そして、つい読んでしまってまた騙される。まるで人格障害のあるタチの悪い女みたいなもの。それがコメントだ。
じゃあ、なんでそんなコメントを書いてしまうかと言えば、他者からの強制されてということを除けば、「コメントがないと読めないコード」を書いてしまっているからだ。「コメントがないと読めないコード」になる原因は、
- 暗号化された名前(勝手な略語とか)
- 過剰に凝ったコード(ドキュメント化できないアルゴリズムとか)
- 妙なトリック(こっそりフラグを渡すとか)
によるところが多い。これらを排除する努力をすれば、「コメントが書きたい」という内なる欲求はまず起きないはずだ。それが独り善がりの結果であろうと B)
これらの原因は、「コメントが書きたい」という悪しき欲求を起こすだけではなく、コードの品質を下げる。これらの原因は「品質の低いコードを書くための掟」と、完全に一致するのだ。
となれば、「コメントを書かない努力」をすることと「コード品質を下げない努力」というのは一致する。「コメントを書きたい欲求」というのは、「コード品質の良くする努力を怠る」ということにつながる。だから、「コメントを書いたら負け」だと言うのだ。だから私はコメントを書かない。書かないための努力をする。
JavaDocやDoxyGenが処理するための「タグ入りコメント」は、時々「書きたいなぁ」と思うことがある。書いておけばみんなが幸せになるような気がする。とは言え、これらについては「継続的にメンテするモチベーション」の問題があって、いつの間にか嘘になってしまう危険がある。コメントに嘘が書いてあるとエラーになるようなシステムであれば、メンテもするだろうしメンテを忘れることもないだろうが、「経年劣化」するままのコメントというのは、「騙される」という点で有害だと思う。ライブラリ的に使われるものは仕方がないが、そうでないものは、やはり書くべきではないと思う。
また、どれだけていねいにコメントを書いても、そのコメントは完全ではない。完全なコメントが書けるくらいなら、完全なコードも書けるはずで、そんな立派なプログラムならそもそも「参考書」以外の理由でコードを読む必要はなかろう。しかし、現実にはいくらメンテをマメにやって「嘘」を排除したところで、不十分なコメントになってしまう。そんなコメントを鵜呑みにして、影響範囲を読まないでプログラムを修正したら、間違ったプログラムになってしまう。つまり、「コメントの欠陥がコードに伝搬する」ということになる。これを避けるためには、コードを読むことを強制させるしかない。となれば、「コメントを書かない」というのが最上の解決となる。
というような理由から、私は「コメントは書くべきではない」と信じている。これはネタや逆説ではなくて、本気で20年以上やって来たことだ。
まぁこれは「面倒だから書かない」という類の人達の言い訳にされてもらっては困るわけだが。
実は、「コメントを書くべきでない」と思う以前は、私はコメントは冗長なくらい書く人だった。それは、Knuthのwebの影響で、「コードとコメントが混ざっていれば便利だしメンテもしやすい」と思っていたのだ。そのためのツール(と言う程ではないけど)も作ってみたりもしていた。ところが運用していると、結局「嘘をついても平気」というところで、破綻してしまったのだ。それ以来、「コメントは容易に嘘をつく」ということでコメントを嫌うようになった。