プログラムコメントはもっと書かないべき

「プログラムコメントはたくさん書くべき」の方が一般的かもしれませんが、リスクも考えましょう。この記事はプログラムコメントを極力書かないようにしている私のスタンスをまとめてみました。

プログラムコメントのリスクを考えると、書かない方がいい

私はプログラムコメントがリスクの方が高くあまり意味が無いと思うようになってから、なるべく書かないようにしている。例えば次のようなリスクがある。

コメントがメンテされず、コードと乖離してしまう
書くこともないのにやっつけで書いてしまいただのノイズになる

｢コメントがメンテされず、コードと乖離してしまう｣については、他人の作成したコードを改修作業したことがある人なら理解できると思うが、コードを改修するとしてもそのコメントの方が改修しづらい。今行っている改修がこのコメントにどう影響しているのかが判断しづらいので、コメントは放っておきたくなる。そんなことを重ねていると、コメントとコードが乖離してしまってとても困った状況になっていく。

また｢書くこともないのにやっつけで書いてしまいただのノイズになる｣もよくある。プロジェクトの決まり事でとりあえずかくとこんな感じになる。

/**
 * 口座クラス
 */
public class Account {
    …
}

クラス名をみればわかることをわざわざ日本語にしても仕方ない。ほんとにこれだけなら書かない方がいいのに、決まりだから書いたりすることがある。

このように考えていくと、プログラムコメントはとてもリスクが高くて意味の無いことが多いことに気がつく。

プログラミングでコメント機能を最初に教わるときに、こういったリスクの説明をおそらくされない。むしろ講師の人は｢コメントはなるべく書きましょう｣という言い方をする方が多い。それをずっと引きずる人が多いので、コメントをたくさん書きましょうという風潮になっている気がする。ただよく考えると、そんなにウェルカムなものでもない。リスクを考えるべきである。

コメントを書くより｢コードを直す｣を優先すべき

私はコメントを書きたくなってしまったら｢コードを直す｣ことを考えるようにしている。

コメントを書こうとしているときは｢このコードでは他の人に伝わらないかもしれない｣と考えているということなので、根本としてはコードが悪い状態なはず。なのでコメントに頼らないコードにすることを第1に考える。これはその状況になったときだけ考えるのではなく、常日頃から考えているし、考えておかないといけない。

コメントを書くぐらいだったら、ドキュメントを書く

コメントでは直近のコードの説明以外にも、全体像の説明であったり仕様の説明であったりを書きたくなることがある。ただこれはそもそもコメントに書くべき事ではない。ドキュメントにすべきことである。

ただドキュメントにしたところで、ドキュメントがメンテされないとコードと乖離してコメントと同じ問題を抱えてしまう。私はこの問題を｢ドキュメントはそのとき（作成時時点）の考えのスナップショットとする｣という考え方で対処している。時間が経ちすぎていれば参考にしないし、必要な物は何度も作り直すので、更新される。本当に更新され続けるのはほんの一部にしておけば、負担も少ない。