コメントの考え方の全体像
「適切な量のコメント」は、コードの理解を速め、変更を安全にするための最小限の説明です。コメントは“何をしているか”より“なぜそうしているか”を伝えるのが核で、コードで表現できることはコードに任せ、表現しづらい前提・意図・トレードオフだけを補います。量は「将来の自分や他人が3分で意味を掴める」ラインに合わせ、過不足のない密度を目指します。
いつ書くかと、何を書くか（重要ポイントの深掘り）
原則の指針
- 目的: 仕様や設計の意図、非自明な選択（最適化・制約・外部仕様）を書き、実装の詳細はコードで語らせる。
- 粒度: 関数・クラスの入り口で契約（前提、戻り値、例外、スレッドセーフ性）を要約。ブロック内のピンポイントでは“なぜ”だけ補足。
- 陳腐化防止: 変更に弱い「行動の逐語説明」は避け、安定した背景（仕様、数式、参考リンク、バージョン差）に絞る。
書くべき具体
- なぜそのアルゴリズムか: データ分布、計測結果、計算量の理由。
- 境界値や契約の根拠: 入力制約、丸め規則、外部APIの仕様引用。
- 副作用・並行性の意図: ロック方針、可視性、再入可能性。
- 一時的なワークアラウンド: バージョン固定や既知のバグ回避と、撤去条件。
避けるべきコメントと過剰のサイン
NGパターン
- コードの逐語説明: 「i を 1 加算」「ループで回す」など、読み手の目を濁すだけ。
- 嘘をつくコメント: 更新されずコードと不一致。最悪のノイズ。
- 自己明白なラベル: 「getter」「初期化」など、名前で十分伝わるもの。
- 無差別なTODO: 期限や責任のない TODO は溜まるほど読めなくなる。
過剰の見分け方
- 命名で置き換え可能: コメントが関数名・変数名に変えれば要らない内容なら削る。
- 重複: Javadocと行内コメントで同じ説明を二重に書いている。
- 変更耐性が低い: 行の動作を逐一説明していて、リファクタで崩れる。
Javadoc と行内コメントの使い分け
Javadocは「契約」を書く場所
- 対象: 公開メソッド・クラス・インターフェース。
- 内容: 前提条件、戻り値、例外、スレッドセーフ性、計算量の目安、ロケールや時刻扱いなど。
- 効果: ツールチップに出て、利用者の理解が即座に整う。
/**
* 税額を計算する。税額は四捨五入し、合計は税額を加えた整数を返す。
* @param subtotal 0以上
* @param rate 0.0〜1.0、例：0.1は10%
* @return 合計金額（subtotal + rounded tax）
* @throws IllegalArgumentException 前提を満たさない場合
*/
public int taxedTotal(int subtotal, double rate) { /* ... */ }
行内コメントは「なぜ」の補足に限定
- 対象: 非自明な分岐、最適化、外部依存の都合。
- 形式: 1～2行で要点のみ。変更に強い背景情報を添える。
// 入力は外部システムの制約で半角大文字に正規化されている（仕様#12）
var normalized = input.toUpperCase(Locale.ENGLISH);
例題とリライトで学ぶ「適量」
例 1: 悪いコメントを削って良い命名へ
悪い例（逐語説明）:
// iを0にする
int i = 0;
// iがaの長さ未満の間ループする
for (; i < a.length; i++) {
// a[i]を出力する
System.out.println(a[i]);
}
良い形（命名で意図を語る。コメント不要）:
for (int index = 0; index < a.length; index++) {
System.out.println(a[index]);
}
例 2: 「なぜ」を1行で残す
// 金融要件：税額を個別に丸め（合計丸めではない）
int tax = (int) Math.round(subtotal * rate);
return subtotal + tax;
例 3: ワークアラウンドに撤去条件を添える
// Workaround: JDK 17u1でCollatorのバグ（JDK-XXXX）があり、PRIMARY指定で誤比較。
// 17u3以上で修正予定。修正後は strength 指定を削除すること。
collator.setStrength(Collator.SECONDARY);
例 4: 並行性の意図を明文化
// 複数スレッドからアクセスされる。valueはAtomicIntegerで可視性と原子性を担保。
private final AtomicInteger value = new AtomicInteger();
適量を保つための習慣とチェックリスト
習慣化
- まず命名: コメントを書きたくなったら、命名で伝えられないかを先に試す。
- “なぜ”に限定: コメントは目的・制約・選択理由だけに絞る。
- 更新の前提: 変更時に必ずコメントを見直す。古いコメントは削除する。
最終チェック
- 必要性: コメントが消えても意味を再構築できるか？できるなら削る。
- 耐久性: 数か月後に読んでも真であり続けるか？
- 場所: 契約はJavadoc、実装の補足は行内コメントに分離されているか？
仕上げのアドバイス（重要部分のまとめ）
コメントは「なぜ」の最小限にとどめ、契約はJavadoc、実装の補足は行内で短く。逐語説明は命名と構造に置き換え、更新に弱いコメントは捨てる。非自明な選択・制約・並行性・ワークアラウンドには根拠と撤去条件を添えて、将来の自分に手がかりを残す——この型が身につけば、コメントは少なく、価値が高く、コードは読みやすくなります。