ネタ元：コメントについて考えているうちに思考が思考膿漏(空転)しています
自分の場合ドキュメント用のJavaDocは書きますが、ラインコメントなんて殆ど書きません。ラインコメントを書かない分、
- Javadocに詳しく書く
- シンプルに短くコードを書く
- 変数名やクラス名やメソッド名を分かりやすく書く
というような点に拘っています。Javadocには、
- 何をするのか
- 引数はどういうものでなければならないのか
- 戻り値はどういう値か
- どういう条件で例外がスローされるか
を明記します。特に重要なのが例外のスローですね。Javadocに例外の条件を予め明記しておけば、catch節にわざわざ「XXXなので例外をスロー」なんてコメントは一切要りません。Javadocはキチンと書けばテストケースの条件にもなりますし、外部ドキュメントとしても残ります。なのでJavadocに注力する分ラインコメントは全く無視なのです。
他に命名をキチンとすることによってコメントを省く事ができます。例えば、AccountManagerというクラスがあってloginというメソッドがあり、引数はuserIdとpasswordの文字列型だとしたら、呼び出すところで「ログインを行う」なんて書く必要はありません。書いている事を見れば一目瞭然なのですから。そういう意味で名前がコメントの変わりとなるのです。
でも稀にラインコメントを書くこともあります。ロジックが複雑で1メソッドに処理が集約される場合ですね。それでも、「XXXデータの最適化を行う」とか「YYYの検索条件を解析する」とか、大きなブロック単位でしか書きません。ラインコメントがなければ理解できないようなコードは、極力書いてはいけないというのがポリシーですね。
ぶっちゃけると、コメントを書かなくなったのはオープンソースのライブラリのコードを読んだり、製品のコードをリバースして仕様を調査したりという事を続けていたので、コメントを読まなくてもコードの意図が読めるようになったからです。オープンソースのコードを読むと、殆どのコメントが英語なんですが、自分は英語に強くないので、コードからコメントの英文の意味を知る方が多いのですね。あとはリバースすれば当然コメントなんてありません。コードしか読むものがないのです。