ソースコードのコメントについて

パッケージソフトの開発に携わっていると、長期的にメンテナンス・機能追加を繰り返すためソースコードの保守性をいやがおうにも意識することになります。

ソースコードの保守性の観点から私が嫌いなのが、「不要なコメント」です。

その際たるものが、修正箇所の最初と最後に「日付　名前　開始（終了）」を記入しているだけのコメントです。まっとうな開発であれば何らかのソースコードバージョン管理ツール（subversionやCVS）を使っているでしょうから、全くの無意味です（継続的な修正や機能追加でこういったコメントが累積していってはたまりません）。

これは極端な例としても、私は極力コメントをソースコードに入れないほうがいいと思っています。私なりのソースコードコメントについてのスタンスは以下の通りです。

クラス・メソッドに対しては、コメントをきちんと書く。クラスやメソッドに対しては、多くの言語では標準のコメント書式があるので（javaならjavadoc）、その書式に従って「クラスの役割」・「メソッドの役割」を明確にする。

メソッド中の処理については、原則としてコメントを書かない。複雑な処理をする部分でコメントを書きたくなるかもしれないが、その場合は、その複雑な処理をメソッドとして切り出してメソッドにコメントを書く（そもそも、その複雑な処理が必要かどうかも考える必要がある）。

変数の説明のためのコメントも原則として書かない。変数の意味は、その変数の名称で判別できるようにするべき。そうしないと、変数の意味をコメントで覚えておいてから続きを読まなければならなくなる。

例外としては、サンプルコードです。
サンプルコードの場合は、APIの使い方などを第3者に説明するためにあるので、それぞれの処理が何を意味しているのかを丁寧に書いた方がいいと思っています。

私自身完全にその通りにしているかというと、時にはメソッド中の処理や変数にコメントを付けることはあります。しかし、安易にコメントに頼ることなく上記のようなことを心がけることで、より可読性・保守性の高いコードを書くことができると考えています（もちろん、他にも大切なことはたくさんありますけどね）。