Javaのコメント記法

Javaでは3種類のコメント記法が提供されています：

単一行コメント

行末までをコメントとして扱います。短い説明や、特定の行の補足に適しています。

// これは単一行コメントです
int count = 0; // カウンター変数の初期化

複数行コメント

複数行に渡る説明を記述できます。コードブロックの説明や、一時的に複数行のコードを無効化する際に使用します。

/* 
 * これは複数行コメントです。
 * 長い説明を記述できます。
 */
int result = calculate(); /* 計算結果を
                            格納します */

ドキュメンテーションコメント（JavaDoc）

API仕様書を生成するためのコメントです。クラスやメソッドの仕様を記述します。

/**
 * ユーザー情報を管理するクラス。
 * システム全体でユーザーの登録や認証を担当します。
 */
public class UserManager {
    /**
     * 指定されたIDのユーザーを取得します。
     * @param id ユーザーID
     * @return ユーザーオブジェクト。該当するユーザーが存在しない場合はnull
     * @throws IllegalArgumentException IDが無効な場合
     */
    public User getUser(String id) {
        // メソッドの実装
    }
}

JavaDoc

JavaDocは、JavaプログラムのAPIドキュメントを生成するための公式ツールです。ソースコード内の特別な形式のコメントから、HTML形式の仕様書を生成します。

基本的なタグ

JavaDocでは、以下のような標準タグを使用できます：

@param - メソッドの引数の説明
@return - 戻り値の説明
@throws - 発生する可能性がある例外の説明
@see - 関連する他の要素への参照
@since - 導入されたバージョン
@deprecated - 非推奨である理由と代替手段

/**
 * 商品の在庫を管理するクラス。
 * 
 * @author 開発部
 * @version 1.0
 * @since 2024-01-01
 */
public class InventoryManager {
    /**
     * 指定された商品の在庫数を更新します。
     * 
     * @param productId 商品ID
     * @param quantity 在庫数
     * @return 更新後の在庫数
     * @throws IllegalArgumentException 商品IDが無効な場合
     * @throws StockException 在庫数が負数の場合
     * @see ProductManager
     */
    public int updateStock(String productId, int quantity) {
        // メソッドの実装
    }
}

JEP 467: Markdown Documentation Comments

Java 21から導入された新機能で、JavaDocコメントでMarkdown記法が使用できるようになりました。これにより、ドキュメントの記述がより直感的になります。

主な特徴

Markdown記法のサポート： 複雑なHTMLタグの代わりに、シンプルなマークダウンが使用できます。
既存JavaDocとの互換性： 従来のHTMLベースの記法も引き続き使用できます。
コードスニペット機能： @snippetタグによる、より柔軟なコード例の記述が可能です。

記述例

Point.java

// Point.java
package com.example;

/// A point in a 2-dimensional space.
/// 
/// # Examples
/// 
/// ```java
/// Point p = new Point(10, 20);
/// p.move(5, -3);
/// System.out.println(p.getX()); // prints 15
/// ```
/// 
/// # Implementation Notes
/// 
/// This class is immutable and thread-safe.
public class Point {
    private final int x;
    private final int y;
    
    /// Creates a new point at the specified coordinates.
    /// 
    /// # Parameters
    /// 
    /// * x   the x coordinate
    /// * y   the y coordinate
    /// 
    /// # Throws
    /// 
    /// * IllegalArgumentException  if coordinates are out of bounds (-100 to 100)
    public Point(int x, int y) {
        if (x < -100 || x > 100 || y < -100 || y > 100) {
            throw new IllegalArgumentException("Coordinates must be between -100 and 100");
        }
        this.x = x;
        this.y = y;
    }

    /// Returns a new point that is offset from this point.
    /// The original point remains unchanged.
    /// 
    /// Example usage:
    /// ```java
    /// Point p1 = new Point(0, 0);
    /// Point p2 = p1.move(5, 10);
    /// ```
    /// 
    /// @param  dx  the distance to move along the x axis
    /// @param  dy  the distance to move along the y axis
    /// @return     a new point with the specified offset
    /// @see        [#getX()]
    /// @see        [#getY()]
    public Point move(int dx, int dy) {
        return new Point(x + dx, y + dy);
    }

    /// Returns the x coordinate of this point.
    /// 
    /// # Returns
    /// 
    /// the x coordinate
    public int getX() {
        return x;
    }

    /// Returns the y coordinate of this point.
    /// 
    /// # Returns
    /// 
    /// the y coordinate
    public int getY() {
        return y;
    }
}

module-info.java

// module-info.java
module com.example {
    exports com.example;
}

コメントの書き方のベストプラクティス

効果的なコメントを書くためのガイドラインです：

必要な場所に書く： コードだけでは意図が分かりにくい箇所に記述します。
簡潔に書く： 冗長な説明は避け、要点を絞って記述します。
最新の状態を保つ： コードの変更に合わせて、コメントも更新します。
なぜそうしたのかを説明する： 実装の理由や背景を記録します。

コメントを書く際の注意点

コメントは有用なツールですが、以下の点に注意が必要です：

自明な内容は書かない： コードを読めば明らかな内容をコメントで繰り返さない。
コードの代わりにしない： 分かりにくいコードを補完する目的でコメントを使わない。
古いコメントを放置しない： 誤解を招く可能性があるため、定期的に見直す。
コメントに頼りすぎない： まずはコード自体を分かりやすくすることを心がける。