Java | 基礎文法：JavaDoc コメント

JavaDoc コメントの全体像

JavaDoc コメントは「コードから自動生成できる公式ドキュメント」のためのコメントです。/** ... */ の形式で書き、メソッドやクラスの「目的」「前提」「戻り値」「例外」「使用例」などを機械可読にします。良い JavaDoc は「契約」を明確化し、IDE のヒントやウェブドキュメントにそのまま役立ちます。

基本書式と配置

コメントの書式と付ける場所

/**
 * 小計に会員割引を適用する。
 *
 * @param subtotal 税抜きの小計（0以上）
 * @param memberYears 会員年数（0以上）
 * @return 割引後の金額
 * @throws IllegalArgumentException 引数が負の場合
 */
public static int discount(int subtotal, int memberYears) {
    if (subtotal < 0 || memberYears < 0) throw new IllegalArgumentException();
    int rate = (memberYears >= 5) ? 10 : 5;
    return subtotal * rate / 100;
}

/**
 * 小計に会員割引を適用する。
 *
 * @param subtotal 税抜きの小計（0以上）
 * @param memberYears 会員年数（0以上）
 * @return 割引後の金額
 * @throws IllegalArgumentException 引数が負の場合
 */
public static int discount(int subtotal, int memberYears) {
    if (subtotal < 0 || memberYears < 0) throw new IllegalArgumentException();
    int rate = (memberYears >= 5) ? 10 : 5;
    return subtotal * rate / 100;
}

対象の宣言直前に /** ... */ を置きます。1行目は短い要約、次に詳細説明、その後にタグ（@param, @return, @throws など）を並べます。要約は「一文」で動詞から始めると読みやすく、IDE のポップアップにも綺麗に出ます。

クラス・フィールド・コンストラクタへの記述

/**
 * 会員の基本情報を保持する不変クラス。
 * 名前と年齢のみを管理し、スレッドセーフ。
 */
public final class Member {
    private final String name;
    private final int age;

    /**
     * 名前と年齢でインスタンスを作成する。
     *
     * @param name null不可、空は許容
     * @param age 0以上
     */
    public Member(String name, int age) { this.name = name; this.age = age; }

    /** 名前を返す。nullは返さない。 */
    public String name() { return name; }

    /** 年齢を返す。負の値はありえない。 */
    public int age() { return age; }
}

/**
 * 会員の基本情報を保持する不変クラス。
 * 名前と年齢のみを管理し、スレッドセーフ。
 */
public final class Member {
    private final String name;
    private final int age;

    /**
     * 名前と年齢でインスタンスを作成する。
     *
     * @param name null不可、空は許容
     * @param age 0以上
     */
    public Member(String name, int age) { this.name = name; this.age = age; }

    /** 名前を返す。nullは返さない。 */
    public String name() { return name; }

    /** 年齢を返す。負の値はありえない。 */
    public int age() { return age; }
}

クラスは「役割・不変条件・スレッド安全性」などの概要を中心に。コンストラクタは引数の前提を明記します。

主要タグの使い方（重要ポイントの深掘り）

@param, @return, @throws の基本

/**
 * 文字列を区切りで連結する。
 *
 * @param sep 区切り文字。null不可
 * @param parts 連結対象。null可、空なら空文字を返す
 * @return 連結結果
 * @throws NullPointerException sepがnullのとき
 */
public static String join(String sep, String... parts) { ... }

/**
 * 文字列を区切りで連結する。
 *
 * @param sep 区切り文字。null不可
 * @param parts 連結対象。null可、空なら空文字を返す
 * @return 連結結果
 * @throws NullPointerException sepがnullのとき
 */
public static String join(String sep, String... parts) { ... }

「何を受け、何を返し、どんな異常を投げるか」を型と補足で具体化します。null 許容性や範囲、単位などを必ず含めると誤用が減ります。

@see, @since, @deprecated で関係性と履歴を示す

/**
 * 合計値を計算する。
 *
 * @see #average(int[]) 平均値の計算
 * @since 1.2
 * @deprecated 2.0 以降は {@link #sumLong(long[])} を使用
 */
@Deprecated
public static int sum(int[] arr) { ... }

/**
 * 合計値を計算する。
 *
 * @see #average(int[]) 平均値の計算
 * @since 1.2
 * @deprecated 2.0 以降は {@link #sumLong(long[])} を使用
 */
@Deprecated
public static int sum(int[] arr) { ... }

@see は関連 API への導線、@since は導入バージョン、@deprecated は非推奨の理由と代替策を明記します。@Deprecated アノテーションも忘れずに。

@link, @code, {@literal} で読みやすさを上げる

/**
 * {@link java.util.List} を {@code String} に整形する。
 * 区切りは {@literal ", "} を使用する。
 */
public static String format(java.util.List<String> list) { ... }

/**
 * {@link java.util.List} を {@code String} に整形する。
 * 区切りは {@literal ", "} を使用する。
 */
public static String format(java.util.List<String> list) { ... }

{@link} は型やメンバーへハイパーリンク、{@code} は等幅表示、{@literal} は記号をそのまま表示します。説明中にサンプルを入れると理解が速くなります。

良い JavaDoc の書き方（重要部分の深掘り）

「何を、なぜ、前提と例外」を短く具体的に

1文の要約で目的を示し、前提（null可否、範囲、スレッド安全性、単位）をタグで明確化します。異常系は「いつ、何を投げるか」を決め、例外の意味がわかるようにします。コードからは分からない「ビジネスルール」や「仕様の出典」を短く添えると保守性が上がります。

呼び出し側が迷わない情報を優先

戻り値の意味（空文字を返すか、Optional を返すか）、計算量の目安（線形・対数）、副作用の有無（外部状態を変更するか）など、使う側の意思決定に直結する情報を書きます。内部実装の詳細は原則書かず、契約に集中します。

一貫性と更新の習慣

変更で契約が変わったら必ず JavaDoc を更新します。要約は動詞から始める（「〜する」）、タグの順序は @param→@return→@throws→@see→@since→@deprecated などに統一すると、読む人の負担が減ります。

使用例（サンプルコード付きの JavaDoc）

メソッドに使用例を含める

/**
 * 先頭が一致する最初の要素を返す。
 * 入力が小規模（~1万件）を想定し線形探索を採用。
 *
 * <pre><code>
 * String[] arr = {"java", "js", "kotlin"};
 * String s = findStartsWith(arr, "ja"); // "java"
 * </code></pre>
 *
 * @param arr 探索対象。null不可
 * @param prefix 先頭一致の文字列。null不可
 * @return 見つかった最初の要素。見つからない場合はnull
 */
public static String findStartsWith(String[] arr, String prefix) { ... }

/**
 * 先頭が一致する最初の要素を返す。
 * 入力が小規模（~1万件）を想定し線形探索を採用。
 *
 * <pre><code>
 * String[] arr = {"java", "js", "kotlin"};
 * String s = findStartsWith(arr, "ja"); // "java"
 * </code></pre>
 *
 * @param arr 探索対象。null不可
 * @param prefix 先頭一致の文字列。null不可
 * @return 見つかった最初の要素。見つからない場合はnull
 */
public static String findStartsWith(String[] arr, String prefix) { ... }

<pre><code>...</code></pre> で整形済みコード例を載せると、使い方がひと目で分かります。可能なら「入力」「期待出力」を含めます。

パッケージ・モジュールのドキュメント

package-info.java でパッケージの説明を書く

/**
 * 支払いドメインのモデルとサービス。
 * 不変モデルを中心に、外部I/Oは別パッケージへ分離。
 */
package com.example.pay;

/**
 * 支払いドメインのモデルとサービス。
 * 不変モデルを中心に、外部I/Oは別パッケージへ分離。
 */
package com.example.pay;

パッケージの方針や依存方向、命名規約をここにまとめると、開発者が素早く把握できます。

モジュール（module-info.java）にも概要を

Java 9 以降のモジュールでも、公開パッケージの意図や利用上の注意を概要として書いておくと、採用時の誤解が減ります。

生成と閲覧（javadoc ツール）

ドキュメント生成の最小例

javadoc -d docs -sourcepath src/main/java -subpackages com.example

-d で出力先、-subpackages で対象を指定します。生成後は docs/index.html をブラウザで開けば、クラスやメソッドの JavaDoc を閲覧できます。ビルドツール（Maven/Gradle）でもゴール/タスクとして自動生成できます。

仕上げのアドバイス（重要部分のまとめ）

JavaDoc は「契約の言語」。1文要約で目的を伝え、タグで前提・戻り値・例外を明確化し、使用例とリンクで迷いをなくします。呼び出し側が判断に必要な情報（null可否、範囲、計算量、副作用）に集中し、出典や仕様の背景は短く添える。一貫性のあるスタイルで書き、変更時は必ず更新。package-infoでパッケージの方針も文書化する——この習慣が、チームの速度と品質を底上げします。