実行できるJavaドキュメント: コメント

Q: Javaでコメントはどう書きますか？

単一行コメントには // を使います。その行で // 以降に書かれたものはコンパイラに無視されます。複数行にまたがるコメントは、テキストを / と / で囲みます。たとえば // これはメモです や / これは 複数行にまたがります / のように書きます。

Q: Javaの // と /* */ の違いは何ですか？

// は1行の残りをコメントにするので、各行ごとに必要です。/ / は / で始まり、閉じる / まで続くブロックコメントで、何行にもまたがって有効です。短い行内メモには // を、まとまったテキストやコードをコメントアウトしたいときには / / を使いましょう。

Q: Javadocコメントとは何ですか？

Javadocコメントは /**（アスタリスクが2つであることに注意）で始まり、クラス・メソッド・フィールドのすぐ上に置きます。javadoc ツールがこれらを読み取ってHTMLのAPIドキュメントを生成し、IDEはホバー時のツールチップとして表示します。内部では @param、@return、@throws などのタグを使って動作を記述できます。

コメントの役割

コメントとは、Javaコンパイラが完全に無視するソースコード内のテキストです。実行中のプログラムの一部になることは決してなく、コードを読む人間のためだけに存在します。コメントは、何かがなぜ特定の方法で行われているかを説明したり、メモを残したり、コードを削除せずに一時的に無効化したりするために使います。

Javaには3種類のコメントがあります。単一行（//）、複数行のブロックコメント（/* */）、そしてJavadocドキュメントコメント（/** */）です。どれもコンパイル時に無視されるという同じ基本的な役割を果たしますが、状況に応じて使い分けます。

単一行コメント

2つのスラッシュ（//）は、現在の行の終わりまで続くコメントを開始します。コンパイラは // から改行までのすべてを読み飛ばします。

public class Main {
    public static void main(String[] args) {
        // コンソールにあいさつを出力する
        System.out.println("Hello, Java!");

        int score = 90; // コメントはコードの後ろに置くこともできる
        System.out.println(score);
    }
}

2つ目のコメントが実際のコードと同じ行を共有していることに注目してください。// より前の部分は通常どおり実行され、その後ろの部分だけが無視されます。これは短いメモに最もよく使われるコメントスタイルです。

複数行ブロックコメント

メモが数行にわたる場合は、各行に // を付けるより、ブロックコメントのほうがすっきりします。ブロックコメントは /* で始まり、*/ で終わります。その間にあるものは何行であっても無視されます。

public class Main {
    public static void main(String[] args) {
        /*
         * このプログラムはブロックコメントを示します。
         * 各行の先頭のアスタリスクは、読みやすさのための
         * 慣習にすぎず、必須ではありません。
         */
        System.out.println("Block comments are handy.");
    }
}

左端にそろえた * は文体上の慣習であって、規則ではありません。実際に意味を持つのは、開始の /* と終了の */ だけです。

コードをコメントアウトする

コメントは、試行錯誤の最中にコードを削除せずに無効化する標準的な方法です。1行なら //、複数行を一度に無効化するならブロックコメントを使います。

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

実行すると、「runs」を含む2行だけが出力されるのがわかります。コメントアウトされた println の呼び出しはコンパイラからは見えません。

よくある落とし穴: ブロックコメントは入れ子にできません。前にいくつ /* があっても、最初の */ がコメントを閉じます。そのため、/* ... */ ブロックを別の /* ... */ ブロックの中に入れることはできません。内側の */ で全体が終了し、残りが構文エラーになります。すでにブロックコメントを含む範囲を無効化する必要があるときは、各行に // を使ってください（ほとんどのエディタはキーボードショートカット一つでこれを行えます）。

Javadocドキュメントコメント

Javadocコメントはブロックコメントに似ていますが、/**（アスタリスク2つ）で始まります。クラス・メソッド・フィールドをドキュメント化するためのもので、説明対象のすぐ上に置きます。javadoc ツールはこれらを閲覧可能なHTMLのAPIドキュメントに変換し、IDEはホバー時のツールチップとして表示します。

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

@param、@return、@throws といったタグは、ツールが理解する構造化されたフィールドです。コンパイラにとっては依然として無視されるコメントにすぎず、その価値は生成されるドキュメントと、IDEが他の開発者（そして半年後の自分自身）に与えるヒントに完全にあります。

良いコメントとノイズ

コメントは、コードがそれ自体では語れないことを説明すべきです。単にコードを言い換えるだけのコメントは雑然とした印象を与え、コードが変わるにつれて古びてしまいがちです。

// 悪い例: コードが明らかにしていることをただ繰り返している
int i = i + 1; // i に 1 を足す

// より良い例: コードでは示せない理由を説明している
retries++; // バックオフして再試行する。APIは5リクエスト/秒に制限されている

明確な名前と構造によってコード自体を読みやすくすることを目指し、コメントはなぜに取っておきましょう。意図、トレードオフ、エッジケース、文脈へのリンクなどです。分かりにくい1行を説明するためにコメントを書いている自分に気づいたら、それはたいてい、代わりに変数名を変えたりメソッドを抽出したりすべきだというサインです。

次へ: 変数

コードに注釈を付けられるようになったので、次の構成要素はそこにデータを格納することです。次のページでは変数を扱います。変数の宣言方法、変数が保持する型、そしてJavaが静的型付けであるがゆえに課すルールについて解説します。

よくある質問

Javaでコメントはどう書きますか？

単一行コメントには // を使います。その行で // 以降に書かれたものはコンパイラに無視されます。複数行にまたがるコメントは、テキストを /* と */ で囲みます。たとえば // これはメモです や /* これは複数行にまたがります */ のように書きます。

Javaの // と /* */ の違いは何ですか？

// は1行の残りをコメントにするので、各行ごとに必要です。/* */ は /* で始まり、閉じる */ まで続くブロックコメントで、何行にもまたがって有効です。短い行内メモには // を、まとまったテキストやコードをコメントアウトしたいときには /* */ を使いましょう。

Javadocコメントとは何ですか？

Javadocコメントは /**（アスタリスクが2つであることに注意）で始まり、クラス・メソッド・フィールドのすぐ上に置きます。javadoc ツールがこれらを読み取ってHTMLのAPIドキュメントを生成し、IDEはホバー時のツールチップとして表示します。内部では @param、@return、@throws などのタグを使って動作を記述できます。