【初心者向け】Javaのコメントの書き方を徹底解説！単一行・複数行コメントの基本とベストプラクティス

コーディングをしているとき、頭の中にあるのは「コンピュータが自分の書いたコードをどう処理するか」ということでしょう。しかし、それと同じくらい重要なのが「人がそのコードをどう読むか」という視点です。

チームでプロジェクトを進めている場合でも、個人で何かを作っている場合でも、コードを適切にドキュメント化することは欠かせません。そこで役立つのがコメントです。

コメントとは、プログラム内に記述された1行または複数行のテキストのことで、コンピュータには無視されます。コメントは、コードを読む可能性のある人間（自分自身や他の開発者）に対して、プログラムの意図を説明するために使われます。

この記事では、Javaでコメントを書く方法を解説し、効果的なコメントを書くためのベストプラクティスも紹介します。

Javaのコメントとは？なぜコメントが必要なのか

プログラミング初心者の方は、「なぜコードにコメントを書く必要があるのか」と疑問に思うかもしれません。コードコメントが重要である理由は、主に次のとおりです。

コードを書くとき、そのコードは必ず誰かに読まれるということを認識しましょう。たとえその「誰か」が未来の自分自身であったとしてもです。さらに、コードを読む人があなたの意図を正確に理解できるとは限りません。

一人で作業している場合、コメントのないコードは「この部分は何をしているんだっけ？」と悩む原因になり、コードの仕組みを思い出すのに余計な時間を費やすことになります。チームで作業している場合は、その影響はさらに大きくなります。他の開発者があなたのコードについて質問するために時間を取られ、貴重な開発リソースが消費されてしまうからです。

総じて言えるのは、コメントを書くことでコードの可読性が向上するということです。特に複雑な処理を書くときは、コードの横に平易なテキストで意図を説明しておくと、後から見返したときに非常に役立ちます。

なお、優れたコメントとは、コードが「何をしているか」を繰り返すのではなく、「なぜそのような実装にしたのか」という意図を説明するものです。効果的なコメントは読み手の疑問に答え、開発効率を向上させます。

Javaのコメントの基本構文

Javaで書けるコメントには、単一行コメントと複数行コメントの2種類があります。それぞれの書き方と使い分けを見ていきましょう。

単一行コメント（インラインコメント）

単一行コメントは、インラインコメントとも呼ばれ、コード行の末尾に記述します。主に、1行程度の短いコードに注釈を付けたいときに使用されます。

例として、コンソールに「It's Friday」というメッセージを出力するプログラムに、インラインコメントを追加してみましょう。

public class FridayMessage {
    public static void main(String[] args) {
        System.out.println("It's Friday!"); // コンソールに"It's Friday"を出力する
    }
}

インラインコメントは、特定のコード行の意図を説明したいときにだけ使うべきです。インラインコメントが多すぎるコードは、かえって読みにくくなってしまいます。

上記の例のように、コードの動作が一目でわかる場合はコメントの価値は低くなります。コメントを書くときは、「その行の意図を説明する必要があるか」を常に意識しましょう。

複数行コメント（ブロックコメント）

複数行コメントは、ブロックコメントとも呼ばれ、コードのセクション全体を説明するために使用します。複数行にわたるコメントで、通常はファイルの先頭やコードブロックの直前に配置されます。

複数行コメントは /* で始まり、*/ で終わります。Javaソースファイルでの記述例は次のとおりです。

/* これは複数行コメントの例です。
   以下のコードは、コンソールに"It's Friday!"を出力します。
*/
public class FridayMessage {
    public static void main(String[] args) {
        System.out.println("It's Friday!");
    }
}

この例では、コードの最初の3行にコメントが記述されています。

実務では、複数行コメントをファイルの先頭に置き、ファイル自体に関する情報を記載するのが一般的です。たとえば、ファイルの作成者、バージョン、最終更新日などの情報をまとめておくと便利です。

テスト・デバッグ時の「コメントアウト」活用法

コメントには、ドキュメント化以外にもうひとつ重要な役割があります。それが、ソフトウェア開発のテスト・デバッグ段階で、一時的にコードの実行を止める「コメントアウト」です。

例えば、プログラムを実行したところ例外が発生したとしましょう。原因がまだ特定できない場合、問題の切り分けのために一部のコードをコメントアウトすると効果的です。

class FridayMessage {
    public static void main(String[] args) {
        String day_of_the_week = "Friday";
        // System.out.println("It's " + day_of_the_week);
    }
}

この例では、System.out.println で始まる行をコメントアウトしています。コードがエラーを返したため、原因を調査している間、その行を無効化したというわけです。

コメントアウトは、プログラムのロジックを分析するときにも特に役立ちます。複数の実装パターンを試して最も効率的なものを見つけるまで、古いコードをコメントとして残しておく、といった使い方ができます。

ただし、コメントアウトはテスト・デバッグ段階だけに留めるべきです。コメントアウトされたコードを最終的なプログラムに残すと、他の開発者を混乱させ、コードの可読性を損なう原因になります。不要になったコードは、きちんと削除する習慣をつけましょう。

まとめ

Javaには、単一行（インライン）コメントと複数行（ブロック）コメントの2種類があります。これらのコメントはコードをドキュメント化するために使われ、テストやデバッグの際にも活用できます。

コメントを書く習慣をつければ、自分自身にとっても、将来コードを読む他の開発者にとっても、格段に読みやすいコードになります。そして忘れてはならないのは、最高のコメントはコードの背後にある「意図」を説明するものだということです。

さあ、今日からJavaでプロのようにコメントを書いてみましょう！