コメントの全体像
コメントは「コードの意図や背景を言葉で補う」ためのものです。Java では「行コメント」「ブロックコメント」「ドキュメンテーションコメント（Javadoc）」の3種類があり、用途に応じて使い分けます。良いコメントは「なぜそうしたか」を伝え、悪いコメントは「コードと同じことを繰り返すだけ」。まずは用途を正しく選ぶことから始めましょう。
3種類のコメントと基本書式
行コメント（1行だけ説明したいとき）
int retries = 3; // ネットワーク不安定対策の最小リトライ回数
短い補足や、直前の行の意図をサッと伝えるときに最適です。「末尾」か「前の行」に置きます。
ブロックコメント（複数行をまとめて残す）
/*
* 本番環境ではリトライ上限を増やす。
* 値は環境変数で上書きされる可能性あり。
*/
int retries = getRetryLimit();
複数行にわたる背景、手順、注意点などをまとめるときに使います。長くし過ぎず、要点を圧縮しましょう。
Javadoc（API の契約を文書化する）
/**
* 小計に会員割引を適用する。
*
* @param subtotal 税抜きの小計（0以上）
* @param memberYears 会員年数（0以上）
* @return 割引後金額
* @throws IllegalArgumentException 不正な入力値
*/
public static int discount(int subtotal, int memberYears) { ... }
自動生成されるAPIドキュメントの元になります。メソッドの「目的」「前提」「戻り値」「例外」を明確に書くのが基本です。
何を書き、何を書かないか（重要ポイントの深掘り）
「なぜ」を書く。コードにある「何」を繰り返さない
// 悪い例（何をしているかの繰り返し）
i++; // iを1増やす
// 良い例（意図・背景）
i++; // 0を含むIDを避けるため、開始オフセットを補正
コードを読めば分かることは書かず、「仕様の背景」「トレードオフ」「制約」「外部要因」をコメントに残します。
期限とTODOは明確に。曖昧な「あとで」は禁止
// TODO(2025-01-31, ticket#1234): エラーハンドリングを共通化
期限やチケット番号を添えると、放置されにくくなります。プロジェクト運用で検索できる形に統一しましょう。
関数やクラスの契約はJavadoc、局所の補足は行コメント
ドキュメントとコメントの役割分担を明確にすると、情報が重複せずメンテが楽になります。
良いコメントの型（テンプレート思考）
条件・理由・影響の3点セット
// 条件: タイムアウト短縮
// 理由: レイテンシが急増（監視で検知）
// 影響: 再試行回数が増える可能性あり
client.setTimeout(Duration.ofMillis(300));
「いつ」「なぜ」「どう影響する」を1〜3行で端的に。変更の背景を未来の自分に手紙で残すイメージです。
仕様抜粋と出典
/*
* 仕様: 会員年数5年以上で10%引き、それ以外は5%引き。
* 出典: 事業ルールv2.3（2025-01-15）
*/
int rate = (memberYears >= 5) ? 10 : 5;
仕様の一部を要約して出典を添えると、変更時に参照元へたどりやすくなります。
アンチパターンと対策（重要ポイントの深掘り）
コメントでハックを正当化しない。原因に向き合う
// 悪い例: ハックの言い訳
// このsleepがないと動かない
Thread.sleep(100);
// 良い例: 原因・暫定・恒久策
/*
* 暫定: DB接続初期化の待機（イベント未到達のため）
* 恒久策: 接続完了イベント発行（ticket#5678）
*/
awaitReady();
「暫定」と「恒久策」を分けて書き、解決の道筋を残します。
コメントとコードの不整合（腐敗）を防ぐ
- 変更で意味が変わったらコメントも必ず更新する。
- 長文は腐りやすいので要点だけに圧縮する。
- JavadocはCIで生成・レビュー対象にする。
罵倒・私語・冗談は禁止
プロのコードは誰かの教科書になります。感情や内輪話は持ち込まない。事実と意図だけを簡潔に。
実用例で身につける
例 1: アルゴリズムの選定理由を伝える
/**
* 先頭一致で最初の要素を返す。
* 入力が小規模（~1万件）想定のため、線形探索を採用。
* 大規模化したら索引構築を検討（ticket#7890）。
*/
static String findStartsWith(String[] arr, String prefix) {
for (String s : arr) if (s.startsWith(prefix)) return s;
return null;
}
例 2: 外部制約を明示する
/*
* 外部APIのレート制限: 10 req/sec（2025-12 現在）
* バースト時にHTTP 429が返るため、指数バックオフで間隔を調整。
*/
retryWithBackoff(() -> callExternal());
例 3: Javadocで契約を明確化
/**
* 文字列を区切りで連結する。
*
* 前提: partsはnull可。空配列なら空文字を返す。
* 例外: sepがnullの場合、NullPointerException。
*/
public static String join(String sep, String... parts) { ... }
仕上げのアドバイス（重要部分のまとめ）
- コメントは「なぜ」を伝えるツール。コードに書いてある「何」を繰り返さない。
- 使い分けは「行コメント＝局所補足」「ブロックコメント＝複数行背景」「Javadoc＝API契約」。
- TODOは期限・出典・チケットで追跡可能に。仕様の要点は出典付きで残す。
- ハックを正当化せず、暫定と恒久策を分けて書く。変更時はコメントも更新する。
- 短く、具体的に、事実だけ。未来の自分や他人にとって役立つ情報を残す。