プログラム考察：コメント

今、あるソフトウェアの不良の調査をしているのだが、こんなとき役に立つのがコメント。
でも、役に立つコメントと役に立たないコメントがあるわけで。

コメントは、以下の役割がある。

• 処理の意味を示す。これはレベル（ファイル・モジュールレベル、関数レベル、コードレベル）でそれぞれ書くべき内容がある。
  ファイル・モジュールレベルは、そのファイル、モジュールにある関数などの種類を説明する。逆に言うとコメントの説明に合わない関数は、別のファイル、モジュールに入れるべき。
  関数レベルは、関数の仕様を書く。何をする関数か、引数・戻り値の意味を書く。
  コードレベルは、１行～複数行の処理の意味や注意事項を書く。（といっても、”１を足す”とかではなく、”ｘｘインデックスをカウントアップする”といったように、対象は何なのか、それをどうするのかを書く）
• 検索のキーワードとなる。
  デバッグするときに問題となる処理を探すのだが、初めはなにもわからないので、プログラムを読むことになる。全てソースを読むわけにはいかないので、特定のキーワードで検索を行ってあたりを付けることになる。

コメントが書けないということは、その本人が処理を分かっていないということなので、その処理を分かりやすく変えるべきである。

逆にコメントに書いてはいけないというものもある。

• 現状の処理とそぐわないもの。嘘があるとソースを読んでいて混乱する。修正をしたことによって処理が変わるならコメントも変える。訳が分らないソースを読んでいると頭がぼやけるので、コメントを信じてしまう・・・。
• ふざけた内容。顔文字が書いてあったり、なれなれしい風に書いてあったり（”だっちゃ”とか”だよん”とか）すると、こんなこと書いてないで品質を上げろ！とイライラする。
• 保守していると、不要になったプログラムを後で使うかもと思って、処理をコメントにすることがあるけれど、いらね。読みにくいし、検索の邪魔になるし、いいことはない。残す代わりに、こんな修正をしたとコメントに書けばいいじゃん。

あー！もう、ほんと訳が分らんプログラムを読んでいるときにふざけたコメントに当たると、ブチ切れる！！