良いコメント悪いコメント
ためになります。
ほぼ全面的に同意です。ただし、自分がすべてにおいてこのルールを遵守しているかというと、そうでもありません。
それも含めて、コメントについてコメント。
※見出しをお借りしております。
これは常識かと思いますが、コメントに限らず、コーディングルールは一貫性があるべきというのを前提としています。
ライセンス
自動で付けたい。SCM上では付けずに、リリースの時に自動的に付けるとか。
意図の説明
「何」をではなく「なぜか」を書く、ってことですね。
冗長なコメント
"意図の説明"の反対。1行ごとに「何を」のコメントが書かれているコードがあって、とても「すとれすふる」。それも、フレームワークのお約束コードにも1行ごとにコメントがあって（たぶんコピペ）、とても悲しくなります。害はあっても一利なし。
// なんかの検索 // パラメータをnewする Parameter p = new Parameter(); // XXXの設定 p.setXXX("xxx"); // 検索を実行する List result = search(p);
せめて、一連の処理に1行だけ「〜の検索」などのコメントならまだまし。
// なんかの検索 Parameter p = new Parameter(); p.setXXX("xxx"); List result = search(p);
強制されたコメント
付ける時と付けない時の線引きが難しい場合はどちらかに倒すようにしていたので、最初はすべてのJavadocコメントに付けていました。
が、さすがに面倒なので、public以外とgetter/setterは任意にしました。はっきり言って、これでも十分に面倒です。
履歴、属性や署名
バージョン管理システムを使っているにもかかわらず、これがあるとキレそうになります。
ノイズ
「名前見て明らかなもの」については、英語が第一言語でない場合はその限りではないと思います。専門用語や業界用語が入ると、英単語やローマ字では限界があります*1。漢字交じりの名詞の方が明らかに分かりやすい。変数名を漢字にしてしまえば良さそうですが、日本語入力のON/OFFが煩わしいです。
あと、ノイズと分かっていても、コメントを付けない理由を自動的に判別するのが難しい場合は、付けます。IDEによるチェック（EclipseならコンパイラとかCheckStyle）で判断したり。
閉じ括弧のコメント
個人的には使いません。ひと目で分かるような短いブロックには、むしろ邪魔です。でも、仕方なく長くなってしまうブロックの場合は、付けたくなることもあります。
これは、直に書くのではなく、IDEがツールボックスなどで表示してくれるとかの方が良いですね。
HTMLコメント
生成されるHTMLが妥当かどうかは、どっちにしてもjavadocに依存するので、極端にレイアウトが崩れなければ不要です。
pタグは改行で済みます。個人的にcodeタグは使います。リストとかテーブルがひつようなら、いっそプレフォーマット(pre)にしてしまうとか。
*1:変換表をルール化するという手もありそうですが、実現した例が無いもので...
