個人的コメント基準 [Java編]

「どんな基準でコメントしてるの？」と聞かれたときのために。
だいたい30分ぐらいで書いたので抜け漏れいっぱいあると思うけど何となくこんな感じです。

Javadoc

基本的につける。 private はやや優先度が落ちるが、特にそれがメソッドであるならできるだけつける。
Javadoc 側で用意された機構 (return とか) をふんだんに使い、タグもどきの類は絶対に使わない。

Q. private の Javadoc ってドキュメント生成の意味ないじゃん。バカなの？
A. 自動生成でパパっと勘所押さえんだよ。それに補完の Tips だって Javadoc 拾うだろうが。変数名で全部なんとかなるって言っていいのは全人類に叡智を授けてからだ。

Normal

概ね以下のような基準で付ける。

• 最適解だと思えない/特異な/真っ当でない記述 → お気持ち表明程度¹
  • 仕様問題やバグのワークアラウンド
  • APIの制限に対処するもろもろ
  • 触れない/触りたくないクラス起因の問題
  • ほか
• 歴史的事情による記述 → 理由、参考資料へのリンク²
  • 「諸事情により未だJava 6なので: http://~」
  • 「DBがEUC-JPなので」
  • 「バグが仕様になりやがったので: <チケット番号>」
  • ほか
• 一般的に「これを使うべき」とされるものの回避 → 理由、内容、参考資料へのリンク
  • ライブラリのバグや奇妙な仕様³
  • 意図的な仕様違反⁴
  • ほか

Rewrite

以下のようなコメントは可能であれば書き換えるか排除する。
「取得する」「設定する」という言葉が出てきたら大抵は排除対象である。

• 無価値
  • getXXに"XXを取得" "To set XX"
  • setXXに"XXを設定" "To get XX"
  • XX に "XX"⁵
  • ほか
• 冗長
  • [Function] とか [Description] とか⁶
  • interface のコメントを実装側で "上書き" ⁷
  • ほか

---

1. 愚痴半分になりがち。兎角短めに。 ↩

2. 内容が内容なのでこれまた長くなりがち。資料を用意してそっちに書いておくべきだろう。 ↩

3. Hibernate Validator とか。 ↩

4. メールアドレスのバリデーションとか。 ↩

5. 特に serialVersionUID に "serialVersionUID" と書いてあるのはほんと何考えてんだろう。何も考えてないのか。 ↩

6. Javadoc の仕様とか読まないのかな。読まねえんだろうな。 ↩

7. 幸い "interface 側に重要なことが書いてあるのに潰された" なんてことは意外と起きない。大抵コピペだからだ。 ↩