Javadocコメントの書き方 — APIドキュメント化
Javadocは「コードからAPIドキュメント（HTML）を自動生成するためのコメント形式」。読み手に意図や契約を伝え、再利用性と保守性を高めます。初心者は「何を書くか」「どこに書くか」「タグの使い分け」を押さえるだけで十分です。
基本ルールと書式
- 書式:
/** ... */のブロックコメントを、クラス／メソッド／フィールドの直前に書く。 - 先頭に要約文: 最初の1行は「端的な説明」。文末はピリオドで締める（英語文の場合）。
- 詳細は改行で追記: 前提・注意事項・例外条件などをコンパクトに。
- タグで構造化:
@param @return @throws @since @see @deprecatedを必要な分だけ。
/**
* 文字列を先頭だけ大文字化するユーティリティ。
* nullや空文字はそのまま返す。
*/
public final class StringUtils {
/**
* 先頭1文字を大文字化し、残りはそのまま返す。
*
* @param s 対象文字列（null可）
* @return 変換後の文字列。sがnullまたは空ならsをそのまま返す
*/
public static String capitalize(String s) {
if (s == null || s.isEmpty()) return s;
return s.substring(0,1).toUpperCase() + s.substring(1);
}
}
よく使うタグと書き方
- @param: 引数の意味・制約（null許可、範囲、単位）。
- @return: 戻り値の意味・条件（同値返却、例外時の挙動は書かない）。
- @throws: 投げうる例外と「いつ投げるか」（前提違反、外部要因）。
- @since: 導入バージョン。
- @see: 関連APIへのリンク（同クラスなら
#methodName）。 - @deprecated: 非推奨理由と代替手段を必ず記載。
/**
* 年齢文字列を検証して数値に変換する。
*
* @param input 年齢文字列。半角数字のみ（例: "42"）。null不可
* @return 年齢の整数値
* @throws IllegalArgumentException 数字以外／範囲外（0〜150）を検出した場合
* @see #isValidAge(String)
* @since 1.2
*/
public static int parseAge(String input) { ... }
クラス、メソッド、フィールドごとの指針
クラスのJavadoc
- 何者か（役割）を一文で: 例「顧客情報の読み書きを提供するサービス」。
- 設計上の前提／制約: スレッド安全性、不変性、使用方法の概略。
- 関連クラス:
@seeで主要インターフェース／実装をリンク。
/**
* 顧客情報のCRUD操作を提供するサービス。
* スレッドセーフではないため、単一スレッド環境で使用すること。
*
* @see CustomerRepository
*/
public class CustomerService { ... }
メソッドのJavadoc
- 要約＋タグ: 引数／戻り値／例外を「仕様として」明確に。
- 副作用があれば明記: 「外部API呼び出し」「DBを更新」など。
/**
* 指定IDの顧客を削除する。存在しないIDでも例外は投げない（冪等）。
*
* @param id 顧客ID（正の整数）
* @return 削除件数（0または1）
*/
public int deleteById(int id) { ... }
フィールドのJavadoc
- 公開フィールドのみ: 定数に用途・単位・範囲を明記。
/** 接続タイムアウト（ミリ秒）。デフォルト5000。 */
public static final int DEFAULT_TIMEOUT_MS = 5000;
具体例とテンプレート
例題1: 動作が分かる最小Javadoc
/**
* 指定範囲の合計値を計算する。
*
* @param values 対象の整数配列。null不可
* @param start 開始インデックス（0以上）
* @param end 終了インデックス（start以上、配列長以下）
* @return 合計値
* @throws IndexOutOfBoundsException 範囲が不正な場合
*/
public static int sumRange(int[] values, int start, int end) { ... }
例題2: 非推奨APIの案内
/**
* 顧客の同期読み込み。
*
* @deprecated 非推奨。大量データでブロッキングが発生するため、
* {@link #loadCustomersAsync()} を使用すること。
*/
@Deprecated
public List<Customer> loadCustomers() { ... }
例題3: ビルダーのガイド
/**
* アプリ設定のビルダー。
* 必須項目: url。その他はデフォルト値が設定される。
*/
public static class Builder {
/**
* 接続URLを設定する。
*
* @param url 例: https://example.com（null不可）
* @return このビルダー（チェーン用）
*/
public Builder url(String url) { ... }
}
よくあるミスと回避策
- コードの再説明をしがち: 「何をするか」を仕様として書き、実装詳細は控える。
- タグが不足:
@param/@return/@throwsを省略しない。読者は「契約」を知りたい。 - 曖昧な表現: 「だいたい」「たぶん」はNG。条件・範囲・例外を定量的に。
- 非推奨の理由なし:
@deprecatedは代替と理由を必ずセットで。 - 最新化されない: 変更したらJavadocも更新。コメントもソースの一部。
すぐ使えるJavadocテンプレート
/**
* 要約文（一行）。何をする／何者かを端的に。
*
* 詳細説明（必要なら複数行）。前提条件／制約／副作用など。
*
* @param name 入力の意味と制約（null可/不可、形式、範囲、単位）
* @param options 使用するフラグやオプション（デフォルト動作）
* @return 戻り値の意味と条件（何を返すか、空・nullの扱い）
* @throws IllegalArgumentException 入力が契約を満たさない場合
* @throws IOException I/Oエラー時
* @see RelatedClass#method() 関連API
* @since 1.0
*/
public Result doWork(String name, Set<Option> options) { ... }
ドキュメント生成とプロジェクト運用のコツ
- 生成コマンド:
javadoc -d doc -sourcepath src -subpackages com.example（ビルドで自動化すると楽）。 - 統一スタイル: プロジェクトで「要約→詳細→タグ」の順序を共通化。
- 例外ポリシーを共有: どの入力で何の例外を投げるかを明記して、テストと実装のブレを防ぐ。
- リンク活用:
{@link Class#method}と@seeでナビゲーション性を上げる。
まとめ
- Javadocは「APIの契約」を機械可読にする仕組み。最初の一行の要約＋タグの充実で品質が決まる。
- 引数・戻り値・例外・関連リンクを明確にし、変更時は必ず更新する。
- 生成をビルドに組み込み、プロジェクト全体で書式とポリシーを統一すると、生きたドキュメントになる。