プログラミングにおけるコメントの付け方について

プログラムを書く時、どのようなコメントを付けているだろうか！？

コメントの付け方というのは、人によって千差万別である。
プログラマはそれぞれプログラミングにおける「美学」を持っているものだが、それと同じようにコメントもいろいろなスタイルがある。

中には全くコメントを付けないという人も多いだろう。
そのような人たちにその理由を聞くと、たいてい以下のような答えが返ってくる。
いわく「優れたプログラムコードはそれ自体が優れたドキュメントであり、コメントは必要ない」と。

それ、ほとんどの部分でぼくも賛成だ。
詳細なコメントやチャートがないと分からないようなプログラムは、たぶんどこかに問題があるのだ。
本当に優れたプログラムは、すごく複雑なことでも、とても分かりやすいロジックで書かれている。
プログラムを分かりやすく書くというのは、一見簡単そうで、実はすごく難しい。

究極的にはコメントが全くなくても分かるプログラムが理想かもしれない。
だが、プログラムだけで全てを表現できるというケースは少なく、やはり補足という意味でコメントが必要になるケースは多い。
ぼく的には、コメントは以下の場合、必要であると考える。

メモとして使う

プログラムを書いていると、いろいろな問題にぶち当たる。
すぐ解決できるような問題であればいいが、すぐには解決できなかったり、とりあえず後で考えようということはけっこう多い。
こんなコメントを見たことがある人も多いだろう。

	// TODO: エラーハンドリングをちゃんとしよう
	if (retcode != 0)
		return retcode;

直すべきかどうか分からない場合は、こんなコメントを入れたりする。

	// BUGBUG: エラーチェックしなくてもいいの？
	p = GetObjPtr();
	(*p->handle)(p);

これは自分に対する備忘録になると同時に、他のプログラマへのメモにもなる。
業務では多くの人が一つのソースコードをさわる。
このようなコメントがあると、時間的に自分が修正出来なかったコードでも、他の人が直してくれるかもしれない。
コードのレビューをする時の助けにもなるだろう。

中にはコメントであたかも会話しているようなものを見ることもある。
「ちくしょう！誰がこんな設計にしやがったんだ！」愚痴が書いてあったりすることもあって面白い。：）

意味が分かりづらいロジックの補足として

最もコメントらしい使い方がこれだろう。

他人のプログラムを見ていると「これは何でこんなことをしているんだろう？」と思うところに多くぶつかる。
そんなことがないように書くのが優れたプログラムというものだろうが、現実的には納期の問題もあったりして、なかなか難しい。
そこで、分かりづらそうなところにコメントを入れておくと、後で役に立つ。

これは他人が見る時の助けになるだけでなく、自分の助けにもなる。
たとえ自分が全部作ったプログラムであっても、たいてい半年後には何をやっていたのが、きれいに忘れているものだ。
そこでコメントを入れておけば、後で思い出す手がかりになる。

え！？そんな物忘れが早いのって、ぼくだけですか！？＾＾；；

区切りをつけて、見やすくする

関数や宣言などの区切りとしてコメントを入れておくと、それだけで見やすくなる。
処理が長い時は、要所にコメントを入れると、たいぶすっきりする。

コメントがなく、処理がひたすら続いていると、それだけで読むのが苦痛になってしまう。
ブログやウェブの記事だって、段落も章立てもなく、ひたすら文章が続いてると、読むのがつらいよね。
プログラムもある種のドキュメントであるから、見やすさは重要だと思う。

つまり

コメントは、必要な時だけ、それもできる限り少なく、というのがぼくの持論である。

プログラムコードを文章に例えれば、本文はコードそのもので、脚注がコメントに相当すると考える。
脚注があまり多くなりすぎると、文章を読む人は脚注に神経がいってしまい、文章に集中できない。
あくまでも主役はコードであるべきだろう。

詳細なロジックやインタフェースから、データ構造まで詳細に解説したコメントは、コードの概念を伝える上で、役に立つ場合も多いかもしれない。
Javadocのように、コメントがそのままドキュメントになるシステムもよく見受けられる。
だが、ぼくはこの手のコメントは参考程度にとどめ、あまり鵜呑みにしないようにしている。
なぜなら、この手の大きなコメントは最初だけ気合いを入れて作られ、その後アップデートされないことが多いからだ。
プログラムのロジックやインタフェースが変わっても、コメントが同時に変更されることは少ないように思う。

多くのコメントを必要とするならば、プログラムをより分かりやすい形に変更すべきである。
結果的に、その方がプログラムの可視性も上がり、メンテナンスも楽になるのだ。

え？ぼくの書いたプログラム？
まずはコメント以前に、分かりやすいプログラムを書くことが必要ですね。＾＾；；
そもそもこんなこと言ってるのも、ぼくがものぐさで、コメントを多く書くのを面倒がっている言い訳かも。＾＾；；