コメントは注釈

コメントとはソースコードに挿入する事ができる注釈みたいなものである。
注釈とは「本文中の語句に解説を付ける事。」である。
つまり、わかりにくい、伝わりにくいところにだけコメントを記述する必要がある。

必要以上に多すぎてはいけない。
読めばわかるようなコードにコメントを付けてはいけないという事。
コードと同じ意味をコメントで記述する事にも意味を持たない。
それは注釈ではない翻訳だ。

まぁそれでも、関数ヘッダくらいは良いかなとも思う。
説明文書の自動生成くらいには使える。
でも、ソースを読むにあたっては、あまり役に立つとは言えない。
それでも、関数内に無駄に多いコメントよりは良いだろう。

関数内にむやみやたらとコメントが多いと以下のメリット・デメリットがある。

メリット
・なんとなく分かりやすい気がする。

デメリット
・コメントに頼りきったコーディングをするようになる。つまり、「コメントがあるからいいや。」という精神のもとコメントが無いと分からないような命名がされる。
・後から読むときにコメントとコードが同じ内容なので無駄である。その為、１画面に表示されるコード量が減るし、無駄なコメントが目に入るのでわかりにくい。
・仕様変更への対応でコメントを修正し忘れると、コードとコメントがミスマッチになる。つまり２重管理の弊害が出る。ミスリードをまねく。

ちなみに、メリットに挙げた項目は本当はメリットではないと思っている。

コメントを書く局面は下記の通りで良いと思っている

・TODO(最終的には消えるコメント）
・一見しただけじゃ何をやっているか分からないコードへの注釈
（一見しただけで分かるコードに変換し、それでも読み難いならコメントをつける。というステップを踏みたい。）
・なんらかの解説を付けたい時

つまり、ほとんど書かなくても良いって事。

そういえば、以前、「コメントレスコーディングのススメ」というエントリを書いた。
いまでも、それで保守性が上がると思っているし綺麗で整理されたコードになると思っている。