【17】コードに書けないことのみをコメントにする

　「理論と実践は違う」とよく言われますが、その違いは、自分で何かを実践してみると本当によくわかります——これは、コードにつけるコメントについても当てはまることです。コードにコメントをつけるのは、理論的には良いこととされています。「これはどういう処理をするコードなのか」をコメントで詳しく説明するのは、良いこと、役に立つこととされているのです。しかし実際には、コメントを入れたことがかえって害になる場合もよくあるのです。世の中には「文章術」というものがありますが、コメントにも良いコメントを書くための文章術があるのです。中でも特に大事なのは、コメントに「書かなくてよいこと」を見極める技術でしょう。

　文法的に誤ったコードを書けば、コンパイラやインタープリタ等のツールがエラーを発生させ、それを知らせてくれます。またコードに機能的な問題があれば、レビューや静的分析で発見されることもあるし、製品になってユーザが日々使う中で発見されることもあります。しかし、コメントはどうでしょうか。『プログラム書法』という本の中で、著者の Kernighan と Plauger は「たとえコメントを入れても、それが不適切なものであれば価値はゼロ（あるいはマイナス）である」と述べています。そして、そうした不適切なコメントは不適切なコードとは違い、修正されたり削除されたりすることは少なく、コードベースにいつまでも残ってしまうことが多いのです。不適切なコメントが残っていれば、誰かがコードを見る度に集中力が削がれたり、誤った情報を与えてしまうことさえあります。ほんのわずかでも、絶えず、プログラマにとって思考の妨げとなってしまうわけです。

　書いていることが技術的に誤っているわけではないが、コードに何か価値を加えるわけでもない、そういうコメントは、一種の「ノイズ」とみなすことができます。コードに書かれていることをただオウム返しにするだけで、何の情報もつけ加えていないコメントはノイズでしょう——プログラミング言語で一度書いたことを、もう一度自然言語で言ったからといって、正しさが増すなどということはありません。コメントの部分は、実行されるわけではないので、ノイズのようなコメントは、コードを読む時にも実行する時にも、まったく役に立たないわけです。また、コメントの内容は、あっという間に陳腐化する、という点にも注意が必要です。たとえば、コードがどのバージョンなのかを知らせるコメントや、「どのバージョンでどういう修正を加えたか」という履歴を入れてコメントアウトされたコードなどがよくありますが、そのような情報はバージョン管理システムを使えば（はるかに合理的に）得ることができます。

　ノイズのようなコメント、情報の誤ったコメントがコードベースに大量にあると、やがてプログラマはコメントのすべてを無視するようになります。ただ読み飛ばすという人もいれば、コメントが画面から消えるよう対策を講じる人もいます。プログラマという人種は皆、問題を回避することに長けています。自分にとって害になり得るものの存在を察知すれば、すぐにそれを避ける方法を見つけ出します。コメントの部分を「折り畳める」ようにしたり、あるいはコメント部分の色を背景と同じにして見えなくしてしまうこともできます。コメントをフィルタリングするスクリプトを書く人もいるでしょう。しかし、プログラマのせっかくの能力をそんなことに使うのは無駄です。それに中には本当に価値のある、重要なコメントもあるはずなので、それを見逃すのは問題です。こういう問題を防ぐには、コメントを通常のコードとまったく同じように考えて扱うことが重要になってきます。すべてのコメントを読む人にとって価値のあるものにし、そうでないものは即座に削除するか書き直すべきであるということです。

　「読む人にとって価値がある」とは具体的にはどういう意味でしょうか。それは、コードには書いていないことや、コードには書けないことが書いてある、ということです。本来コードを見ればわかるはずのことをコメントに書かなくてはならないのは、コードの構造や書き方を見直す必要があるということです。メソッドやクラスの名前がわかりにくいからコメントを書くというのなら、名前を変えてしまった方がいいでしょう。関数が長くて分かりにくいせいでコメントが要るのなら、関数を小さく分割して、どういう関数かがすぐに分かる名前を個々につける方がいいでしょう。コード自身にできる限り「語らせる」ようにするのです。どうしてもコードに語らせることが不可能な時に、語らせたかったものとコードとのギャップをこそコメントに書くのです。コードに「書いていないこと」ではなく、コードに「書けないこと」のみをコメントにするのです。