コメント（// と /* */ と /** */）

// 一行コメント — // から行末までがコメントになります。
int x = 10; // 行末コメント — コードの後にも書けます。

/*
  ブロックコメント — /* から */ までの範囲がコメントになります。
  複数行にわたるコメントを書くときに使います。入れ子にはできません。
*/

/**
 * Javadocコメント — /** で始めるブロックコメントです。
 * クラス・メソッド・フィールドの直前に書きます。
 * javadoc ツールでHTMLドキュメントを生成できます。
 *
 * @param paramName 引数の説明
 * @return 戻り値の説明
 * @throws ExceptionClass 発生条件の説明
 */

Javadocコメントでは『@』で始まるブロックタグを使って情報を構造化します。IntelliJ IDEAやEclipseなどのIDEはJavadocを読み取り、コード補完やホバー表示に活用します。

『javadoc』コマンドを実行することでHTMLドキュメントを生成できます。

javadoc -d doc -sourcepath src -subpackages com.example

CommentBasic.java

// CommentBasic.java — Java のコメント構文の基本的な使い方です。

public class CommentBasic {

    /* 配列の要素数を定数として定義します */
    private static final int ITEM_COUNT = 3;

    public static void main(String[] args) {
        // 商品名と価格の配列を定義します
        String[] items = {"widget", "gadget", "device"};
        int[]    prices = {1200, 3500, 800}; // 税抜価格

        int total = 0;

        for (int i = 0; i < ITEM_COUNT; i++) {
            System.out.printf("%-10s %5d yen%n", items[i], prices[i]);
            total += prices[i];
        }

        System.out.println("----------");
        System.out.printf("%-10s %5d yen%n", "Total", total);
    }
}

コンパイルして実行すると次のようになります。

$ javac CommentBasic.java && java CommentBasic
widget      1200 yen
gadget      3500 yen
device       800 yen
----------
Total       5500 yen

Calculator.java

/**
 * 数値計算ユーティリティクラスです。
 *
 * 
整数配列を対象とした基本的な統計計算メソッドを提供します。
 *
 * @author example
 * @since 1.0
 */
public class Calculator {

    /**
     * 整数配列の合計値を計算して返します。
     *
     * @param values 合計を計算する整数の配列
     * @return 配列全要素の合計値
     * @throws IllegalArgumentException values が null の場合
     */
    public static int sum(int[] values) {
        if (values == null) {
            // null はサポート外なので例外をスローします
            throw new IllegalArgumentException("values must not be null");
        }

        int total = 0;
        for (int v : values) {
            total += v;
        }
        return total;
    }

    /**
     * 整数配列の平均値を計算して返します。
     *
     * 
配列が空の場合は {@code 0.0} を返します。
     *
     * @param values 平均を計算する整数の配列
     * @return 平均値（double）。配列が空の場合は 0.0。
     * @throws IllegalArgumentException values が null の場合
     * @see #sum(int[])
     */
    public static double average(int[] values) {
        if (values == null) {
            throw new IllegalArgumentException("values must not be null");
        }
        if (values.length == 0) {
            return 0.0; /* 空配列のゼロ除算を防ぎます */
        }

        /* 整数除算を避けるためキャストします */
        return (double) sum(values) / values.length;
    }

    /**
     * @deprecated {@link #average(int[])} を使ってください。
     */
    @Deprecated
    public static double mean(int[] values) {
        return average(values);
    }

    public static void main(String[] args) {
        int[] scores = {85, 92, 78, 95, 60};

        System.out.println("Sum:     " + sum(scores));
        System.out.printf("Average: %.1f%n", average(scores));
    }
}

コンパイルして実行すると次のようになります。

$ javac Calculator.java && java Calculator
Sum:     410
Average: 82.0

Javaのコメントは一行コメント（『//』）、ブロックコメント（『/* */』）、Javadocコメント（『/**』で始めるブロックコメント）の3種類です。一行コメントはコードの右側に補足を添えるときや処理を1行コメントアウトするときに使い、ブロックコメントは複数行の説明に使います。ブロックコメントは入れ子にできない点に注意が必要です。

Javadocコメントはクラス・パブリックメソッド・フィールドの直前に書く慣習があります。『@param』『@return』『@throws』『@deprecated』など豊富なタグで情報を構造化でき、標準ツール『javadoc』でHTMLドキュメントを自動生成できます。JDKのAPIドキュメント自体もこの形式で記述されています。IntelliJ IDEAやEclipseなどのIDEはJavadocを読み取り、コード補完やホバー表示に活用するため、パブリックAPIには積極的に付けておくと利便性が高まります。