【完全ガイド】良いJavaDocの書き方とベストプラクティス

2025年2月21日 2025年2月21日山崎講師

山崎講師

こんにちは。ゆうせいです。

Javaのコードを書くだけでなく、それを他の人が理解しやすくするためには JavaDoc を適切に書くことが重要です。

でも、「どう書けばいいのか分からない」「最低限の説明を書いてるけど、本当に役に立ってるのか不安…」という方も多いのではないでしょうか？

今回は、良いJavaDocの書き方 を詳しく解説します！

JavaDocとは？

JavaDocは、Javaのソースコードにコメントとして記述し、HTML形式のドキュメントを自動生成する仕組み です。

Javaの公式ドキュメント（JDKのAPIリファレンス）もJavaDocを使って作られています。

なぜJavaDocを書くべきか？

可読性向上：チームメンバーがコードを理解しやすくなる
メンテナンス性向上：時間が経っても意味が明確
APIドキュメントの自動生成：クラスやメソッドの説明を統一されたフォーマットで公開できる

JavaDocの基本構文

JavaDocは /** ... */ で囲んで記述します。

/**
 * クラスやメソッドの説明
 * @タグ
 */

基本的なタグ

タグ	説明
`@param`	メソッドの引数の説明
`@return`	メソッドの戻り値の説明
`@throws`	例外をスローする場合の説明
`@deprecated`	非推奨のメソッド・クラスを示す
`@see`	関連するクラスやメソッドへのリンク
`@since`	どのバージョンから存在するか

良いJavaDocを書くためのポイント

1. シンプルで分かりやすく！

JavaDocの目的は「分かりやすく伝えること」です。
長すぎず、短すぎず、要点を押さえた説明 を心がけましょう。

NG例

/**
 * このメソッドは2つの数値を加算します。
 * 2つの数値はint型で、結果もint型です。
 * 計算を行い、その結果を返します。
 */
public int add(int a, int b) {
    return a + b;
}

OK例

/**
 * 2つの整数を加算し、結果を返す。
 *
 * @param a 1つ目の整数
 * @param b 2つ目の整数
 * @return 加算結果
 */
public int add(int a, int b) {
    return a + b;
}

→ 不要な情報を削り、シンプルに説明！

2. 例を入れると分かりやすい！

コード例をJavaDocに含めると、より直感的に理解できます。

/**
 * 指定した数の階乗を計算する。
 * <p> 例: factorial(5) は 120 を返す。</p>
 *
 * @param n 階乗を求める整数 (0以上)
 * @return nの階乗
 * @throws IllegalArgumentException nが負の値の場合
 */
public int factorial(int n) {
    if (n < 0) {
        throw new IllegalArgumentException("n must be non-negative");
    }
    return (n == 0) ? 1 : n * factorial(n - 1);
}

→ @throws で例外の可能性も明記！

3. HTMLタグを活用しよう

JavaDocは HTMLタグをサポート しています。

<p>：段落
<pre>：整形済みテキスト（コードブロックなど）
<code>：インラインのコード
<ul> / <li>：箇条書き

/**
 * ユーザーのステータスを更新する。
 *
 * <p> 以下のいずれかの値を指定可能:</p>
 * <ul>
 *   <li>ACTIVE - アクティブ</li>
 *   <li>INACTIVE - 非アクティブ</li>
 *   <li>BANNED - 禁止</li>
 * </ul>
 *
 * @param userId 更新するユーザーのID
 * @param status 新しいステータス
 */
public void updateStatus(int userId, String status) {
    // 実装
}

→ HTMLタグを使うことで、読みやすいドキュメントが作れる！

JavaDocのベストプラクティス

すべての公開メンバーにJavaDocを書く
- public クラス・メソッド・フィールドには必ずJavaDocを付ける
- private メンバーは不要（チームの方針による）
動詞の現在形を使う
- NG: このメソッドはファイルを開きます。
- OK: ファイルを開く。
型情報を繰り返さない
- NG: このメソッドはint型の整数を返します。
- OK: 整数を返す。
一貫性のあるフォーマットを維持
- チーム内で統一ルールを決める
自明なメソッドには不要 /** * @return ユーザー名 */ public String getUserName() { return this.userName; } → このようなgetterメソッドには不要！

まとめ

良いJavaDocを書くには、シンプル・具体的・統一感 がポイントです！

基本構文をマスター
冗長にならないように簡潔に書く
例を入れるとより分かりやすい
HTMLタグを活用して読みやすく
チームでフォーマットを統一する

JavaDocをしっかり書いておくと、将来のメンテナンスや他の開発者の理解がスムーズになる ので、ぜひ意識して書いてみてください！

セイ・コンサルティング・グループの新人エンジニア研修のメニューへのリンク

投稿者プロフィール

山崎講師代表取締役

セイ・コンサルティング・グループ株式会社代表取締役。
岐阜県出身。
2000年創業、2004年会社設立。
IT企業向け人材育成研修歴業界歴20年以上。
すべての無駄を省いた費用対効果の高い「筋肉質」な研修を提供します！
この記事に間違い等ありましたらぜひお知らせください。