ソースコードのコメントは一切いらないという話

ソースコードのコメントよりも空白行のほうが理解を助けるという研究結果
という記事を読んだ。なるほどな記事である。

無駄なコメントは可読性を落とすだけだから書くなというのは当たり前の話として昔からあった。
//ファイルを開く
open(filename);
みたいなコードは結構あったりする。コードを読めばわかるようなことをいちいちコメントで書くなというわけだ。逆にいうとコードを読むだけで内容が理解できるならコメントなんて一切いらないのでそれが理想となる。

職業プログラマの世界ではコメントがないコードはクズと一緒であるというような誤った考えが広まってしまっていて、ソースコードをツールにかけて、実コード行数あたりコメントがどれくらいあるかという「コメント率」を測定して、指標として扱い、あまりにもコメントがないコードは問題とされたりする。
そんな世界で育ったプログラマは、上記のようなわかりきったコードにもいちいちコメントをつけてしまう。それどころかコード一つに対してコメント一つというようなアホなことを平然とやってしまう。
そういうことを普段からやっていると、コードを読むときにもコメントを頼るようになってしまう。他人のコードを読むときに、コードではなくてコメントだけを拾い読みしてわかったような気になってしまったりする。

コメント頼みは関数の命名センスにも悪影響を与え、どうせコメントで補足できるからと、安易な関数名をつけてしまったりする。もっとひどいと、ひどいコードを書いているのにコメントで言い訳を書いて正当化してしまうこともある。ある意味本当のコメントであるが。

コメントには、コードの補足というよりは、作業の履歴としての意味をもつものもある。例えばバグを管理しているデータベース上の管理番号を、そのバグを修正した箇所につけるといったような。
//バグ修正ここからはじめ
hoge();
//バグ修正ここでおわり
といったものだ。これなんかは最悪で、こんなものはgitの履歴とか他の所で管理しろということになる。

唯一許されるコメントは、whyがぱっと見でわからないような箇所につけるコメントとなる。単純な文一つであっても、直感的にはその場所でそうしている理由がわからないような場合だ。
//ここでhoge()を読んでいるのは一見無意味なように見えるがこうしないと別のスレッドから割り込まれたときにまずくなる。
hoge();
この類のコメントは必須だが、特殊事情を説明することとなるために説明コメントは長文となり、かなり可読性を落とす。

上記はコードの途中のコメントだが、コードの周りにつけるコメントもある。関数の説明や引数や戻り値の説明をヘッダの関数宣言のところに書いたりする。doxygenとかでコメントからAPIドキュメントを手軽に作成するために関数の説明をがっつり書くことも多くなった。
これらはコードの途中にまぎれるわけではないため、直接可読性を低下させないが、例えばヘッダを開いたときに、コメントが一切なければ一画面に収まる関数リストであっても、一つ一つの関数にいちいちコメントがついているために一画面には関数二つくらいしか表示されないといったことになりかねない。引数の型が知りたいだけなのにそんな状況になったら腹が立つだろう。

似たものにライセンスのコメントがある。コードを読むためにファイルを開いたのに表示されたのは画面いっぱいのGPLの説明文だったらたまったものではない。他にもこのコードはだれそれが貢献している的なコメントもある。コードを読ませろぼけと思うのが人情だ。

最近はコメントの一部の機能をアノテーションが担うケースも増えた。しかしこれは結局、XML地獄をアノテーション地獄に変えただけで終わっている。可読性はあがるどころかますます悪くなっている。

コメントには弊害も多く、コードを修正したのにそれに付随したコメントの修正が漏れてしまうということがある。コメントだけを頼りにしている人々はころっと騙されてしまう。
ある箇所を修正して、それによって引数にも修正をいれて、それぞれの箇所のコメントも修正して、さらに関数の説明にも追記をして、なんてやっていたらどこかを忘れるに決まっている。一番最悪なのはコメントだけ直してコードを直さないとか。間違いなくクビが飛ぶ。

もういいかげんコメントはいらないんじゃないかと思うようになった。ためしにコメントを全部除去したコードを見てみると、その整然とした風景にすがすがしさを覚えた。目が上から下にスムーズに流れるのである。途中で止まることがない。頭の中にひっかかりがないのである。コメントが途中に一箇所でもあったら、その内容が関係ないものであってもついつい反応してしまうものだ。
なぜならコメントは異物だからだ。コードという純白の中に墨汁が落ちているようなものだ。

しかしコメントを完全になくすことは出来ないのも事実だ。いくらコメントを減らすリファクタリングをしたって、究極的にはこの箇所には説明が必要というケースは残ってしまう。
こうなってくると、テキストファイルの限界となる。テキストファイルとは本来的に一つのものしか押し込めないようになっている。それによって極大の可搬性を得ているが、そろそろそれを捨て去るときかもしれない。
テキストファイル以外のものでコードを管理すると、可能性が広がるのも事実だ。XMLでも普通のコメントでもなんでもいい。ソースコードに対していくらでも注釈を入れる。ただしエディタからはそれらは見えなくなってコードだけが見える。妥協だがこれしかないのではないか。