プログラムのコメントに『何をしているコードか』を書いても無意味なので、代わりに『なぜそのようなコードになったのか』を書くようにしよう

　タイトルで全部言い切ってしまいましたので、後は冗長に書いてブログエントリーに仕立てます。

　職業上、プログラムを毎日観ていていますが、一番多いコメントが『何をしているコードか』というものです。「ここでトランザクションを開始する」「もしEOFだったらファイルを閉じる」「セミコロンで分割して最初の文字を取得する」などなど……

　それって、要ります？？

　構造や内容については、その言語が読める人なら誰でも解るものです。そもそもコードを読んでる時点で当たり前の部分はクリアしている人のはずなのだから、上記のような『何をしているコードか』は書くまでもないこと*1で、不要なコメントです。

　不要なコメントは削除しましょう。

　コメントはコンパイルするときに無視されるものです。ソースの内容とコメントが食い違っていてもコンパイルエラーは出ません。コメントは増えれば増えるほど、ソースの内容と齟齬があるという危険性が増します。ソースと齟齬があるコメントは、読み手に混乱を与えます。よって、不要なコメントは入れるべきではありません。『何をしているコードか』というコメントは削除対象です。

　ではどういうコメントを残すのか？

　それを考える前に、もうちょっとだけ前提を詰めておきたいです。

　そもそも、コメントを残す目的ってなんでしょう？

　それは『保守者に情報を伝えるため』です。コメントの有無によってプログラムの動作は変わりませんし、コンパイラはコメントを無視します。コンパイラ以外でプログラムに触れるのは保守者ですから、コメントは保守者のためにあると言えます。では何の情報を伝えればいいのでしょうか？　それは『なぜ』です。

　『なぜそのようなコードになったのか』を残すべきです。

　保守者が知りたいのは『なぜそのようなコードになったのか』です。既存のコードに手を入れて変更するにしても、セオリー通りではないコードは、なぜそうなっているのかが解らないと手を入れられません。一見すると冗長でバグがありそうなコードだけれど、もしかしたら複雑な理由があるのかも？　そう考えたら迂闊には手を入れられません。『何をしているコードか』は、時間を掛ければ読み解くことができます。しかし、なぜそうやったのかは書いたプログラマーの頭の中にしかありませんから、コードから読み取ることはできません。だからこそコメントで補完する必要があるのです。更に、保守者への注意喚起まで残っていると素敵。

　プログラマーに話を聴くと、コメントを「なんとなく」で入れている人が結構多いです。コメントはどう書こうがプログラムの内容には影響しないので、あまり重視されていないのでしょう。確かに気持ちも解らなくはないのですが、とはいえ、コメントも成果の一つ。更に、保守者への大事な情報源です。ちょっとばかり気を遣って「なんとなく」で入れるのは止めにしませんか。

*1:説明を書かないと何をやっているのか解らないコードは、それ自体がバグの元なので書きなおすべき