Java道｜Javaコメントの基本と書き方

Java道｜Javaコメントの基本と書き方

コメントは、Javaコードに添える修行メモ。
コンピュータには実行されないけれど、人がコードを理解するための大切な道しるべになる。

Javaのコードは、コンピュータに命令を伝えるために書きます。

けれども、実際にコードを読むのはコンピュータだけではありません。
自分自身も読み返しますし、学習が進めば、ほかの人にコードを見てもらうこともあります。

Javaのコードは、最初のうちは記号や英単語が多く、少し読みにくく感じることがあります。
そんなときに役立つのが コメント です。

コメントとは、コードの中に書ける説明文やメモのことです。プログラムの動作そのものには影響しませんが、コードの意味や目的を人に伝えるために使います。Javaでは、コメントを使うことで、プログラムが何をするものなのか、どの処理がどんな役割を持つのかを分かりやすくできます。

鬼滅の刃の世界観にたとえるなら、コメントは 技の巻物に書き添える修行メモ のようなものです。

コメントは、Javaを学び始めたばかりの人にとって、とても心強い味方です。
短い説明を添えるだけでも、コードの意味がぐっと読み取りやすくなります。

Sample1.javaを見てみよう

この記事では、次の変更後の Sample1.java を使って、コメントの基本を見ていきます。

ファイル名：Sample1.java（変更後）

// Java修行の開始メッセージを表示するプログラム
class Sample1
{
    public static void main(String[] args)
    {
        System.out.println("Java修行を始めます。");
        System.out.println("一歩ずつコードの型を覚えます。");
    }
}

このプログラムでは、mainメソッドの中に2つの System.out.println があります。

実行すると、画面には次のように表示されます。

Java修行を始めます。
一歩ずつコードの型を覚えます。

このコードのいちばん上にある次の行が、今回のテーマであるコメントです。

// Java修行の開始メッセージを表示するプログラム

このコメントは、このプログラム全体が何をするものなのかを説明しています。

コードを読む人は、最初にこのコメントを見ることで、これからJava修行の開始メッセージを表示するプログラムなのだと分かります。

コメントとは何か

コメントとは、コードの中に書く説明文やメモのことです。

Javaの命令として実行されるものではなく、人がコードを理解しやすくするために書きます。

今回の Sample1.java では、次の1行がコメントです。

// Java修行の開始メッセージを表示するプログラム

このコメントは、プログラムの目的を分かりやすく説明しています。

鬼滅風にたとえるなら、コメントは技の巻物に添える注釈です。

たとえば、巻物の先頭に「この型は修行開始の合図を示す」と書いてあれば、読む人はその型の目的をすぐに理解できます。

Javaコードでも同じです。
コメントがあると、コードの中身を見る前に、何をするプログラムなのかをつかみやすくなります。

// から行末までがコメントになる

Javaでは、// を使うと、その位置からその行の終わりまでがコメントになります。

Sample1.java の先頭を見てみましょう。

// Java修行の開始メッセージを表示するプログラム

この場合、// から右側に書かれている内容がすべてコメントです。

Javaのコンパイラは、この部分を命令として扱いません。
つまり、コードの中に書かれていても、実行対象にはなりません。

// は、「ここから先は説明文ですよ」という印だと考えると分かりやすいです。

たとえば、次のように文の後ろにコメントを書くこともできます。

System.out.println("Java修行を始めます。"); // 1行目のメッセージを表示

この場合、System.out.println("Java修行を始めます。"); は実行される文です。
一方、// 1行目のメッセージを表示 はコメントなので実行されません。

Javaのコンパイラはコメントを無視して処理する

コメントの大きな特徴は、コンパイラがコメントを無視して処理することです。

Sample1.java の先頭には、次のコメントがあります。

// Java修行の開始メッセージを表示するプログラム

この行は、人間に向けた説明です。
コンピュータに対する命令ではありません。

そのため、コンパイルして実行しても、このコメントの文章が画面に表示されることはありません。

実際に実行されるのは、mainメソッドの中にある次の2つの文です。

System.out.println("Java修行を始めます。");
System.out.println("一歩ずつコードの型を覚えます。");

実行結果は次の通りです。

ここで大切なのは、コメントに書いた文章は画面には出てこない ということです。

鬼滅風に言えば、コメントは修行ノートであり、実際に放つ技ではありません。
技として動くのは、mainメソッドの中に書かれた文です。

コメントと実行される文の違い

Javaコードを読むときは、コメントと実行される文を区別することが大切です。

Sample1.javaには、説明のためのコメントと、実際に処理される文があります。

// Java修行の開始メッセージを表示するプログラム
class Sample1
{
    public static void main(String[] args)
    {
        System.out.println("Java修行を始めます。");
        System.out.println("一歩ずつコードの型を覚えます。");
    }
}

このうち、コメントは先頭の1行です。

// Java修行の開始メッセージを表示するプログラム

実行される文は、mainメソッドの中の2行です。

System.out.println("Java修行を始めます。");
System.out.println("一歩ずつコードの型を覚えます。");

学習の初期では、どの行が処理されるのかを意識することがとても大切です。

コメントは読みやすさを助けます。
一方で、実際に画面表示を行うのは System.out.println の文です。

コメントは何を伝えているのか

Sample1.javaのコメントは、とても短いですが、役割ははっきりしています。

// Java修行の開始メッセージを表示するプログラム

この1行によって、読み手は次のことを理解できます。

コメントがあると、コードを読む前に全体像をつかめます。

もしコメントがなくても、mainメソッドの中を読めば、何をしているか分かります。
しかし、先にひとことで説明があると、読み手は安心してコードを読み進められます。

鬼滅風にたとえるなら、巻物の最初に「これは修行開始の合図を示す型」と書かれているようなものです。
その説明があるだけで、これから読む型の目的が分かりやすくなります。

コメントを書くとコードが読みやすくなる理由

Javaを含め、プログラムのコードは、自然な文章とは違います。

キーワードや記号が多く、慣れないうちは何をしているのか見えにくいことがあります。

そこでコメントを入れると、コードの読みやすさが大きく変わります。

Sample1.javaのような短いコードでも、コメントがあると、何をするプログラムなのかがすぐに分かります。

学習中は、コメントを自分のための説明書として使うとよいです。
難しい言い回しを使う必要はありません。

まずは、次のように素直な説明で十分です。

// Java修行の開始メッセージを表示するプログラム

Sample1.javaを上から順番に見てみよう

Sample1.javaの中で、コメントがどこにあり、どのような役割を持っているのかを、上から順番に確認します。

// Java修行の開始メッセージを表示するプログラム
class Sample1
{
    public static void main(String[] args)
    {
        System.out.println("Java修行を始めます。");
        System.out.println("一歩ずつコードの型を覚えます。");
    }
}

こうして見ると、コメントは処理の前に置かれていて、これから始まるプログラムの意味を先に教えてくれていることが分かります。

図：コメントと実行される文の違い

↓クリックすると拡大表示されます。

この図は、Sample1.javaの中で、コメントと実行される文がどのように違うのかを表しています。

この図から分かることは、コメントはコードの中に書かれていても、実行の流れには入らないということです。

一方、mainメソッドの中にある2つの System.out.println は順番に実行され、画面に結果を表示します。
コメントは説明役、文は実際に仕事をする命令、と区別して考えると分かりやすくなります。

// を使うコメントは1行だけに向いている

Sample1.javaで使われているコメントは、// を使った1行コメントです。

// Java修行の開始メッセージを表示するプログラム

この形式は、短い説明を書くのに向いています。

// の場合、その行の終わりまでがコメントになります。
そのため、1つの // だけで複数行にわたる説明を書くことはできません。

複数行にしたい場合は、各行に // を付けます。

// Java修行の開始を知らせる
// 2行のメッセージを表示するプログラム

今回のSample1.javaのコメントは1行で内容がまとまっています。

そのため、// の形式にぴったりです。

文の後ろにもコメントを書ける

// コメントは、行の先頭だけでなく、文の後ろにも書けます。

たとえば、Sample1.javaの出力文に説明を添えるなら、次のように書けます。

System.out.println("Java修行を始めます。"); // 1行目を表示
System.out.println("一歩ずつコードの型を覚えます。"); // 2行目を表示

この場合、左側の System.out.println は実行されます。
右側の // から後ろはコメントなので実行されません。

ただし、文の後ろにコメントをたくさん書きすぎると、コードが横に長くなって読みにくくなることがあります。

短い補足なら文の後ろ。
少し詳しく説明したいなら、文の前の行にコメントを書く。
このように使い分けると読みやすくなります。

もうひとつのコメントの書き方である /* */ も知っておこう

Javaには、// のほかに、/* */ を使うコメントの書き方もあります。

この形式では、/* から始まり、*/ で終わるまでの範囲全体がコメントになります。

たとえば、次のように書けます。

/*
 Java修行の開始メッセージを
 2行で表示するプログラム
*/

この書き方では、複数行にわたってコメントを書くことができます。

今回のSample1.javaで使っているのは // のコメントです。
そのため、中心になるのは1行コメントの使い方です。

ただ、Javaには /* */ という書き方もあることを知っておくと、長めの説明を書きたいときに役立ちます。

鬼滅風にたとえるなら、// は巻物の横に書く短いメモです。
/* */ は、少し長めの説明をまとめて書く注釈欄のようなものです。

図：コメントの書き方

↓クリックすると拡大表示されます。

この図は、Javaのコメントの書き方である // と /* */ の違いを整理しています。

この図から分かることは、// は短い1行コメントに向いていて、/* */ は複数行にわたる説明に向いているということです。

Sample1.javaでは // を使って、プログラム全体の目的を1行で説明しています。
まずはこの形に慣れておくと、Javaコードに説明を添える感覚が身につきます。

コメントに書くとよい内容

コメントは自由に書けますが、何でもたくさん書けばよいわけではありません。

大切なのは、コードを読む人の理解を助けることです。

Sample1.javaのコメントは、プログラム全体の目的を説明しています。

// Java修行の開始メッセージを表示するプログラム

このコメントは短いですが、読み手にとって十分分かりやすい内容です。

コメントを書きすぎないことも大切

コメントは便利ですが、書きすぎると逆に読みにくくなることがあります。

たとえば、すでに見れば分かる内容を何度も説明すると、コードよりコメントの方が多くなり、読む流れが悪くなることがあります。

大切なのは、コードの理解を助けるコメントを書くことです。

Sample1.javaのように、プログラム全体の目的を先頭に1行で書くのは、学習初期にとても分かりやすい方法です。

鬼滅風に言えば、修行ノートは大切ですが、巻物のすべての動きに長すぎる説明を書き込むと、かえって型の流れが見えにくくなります。

学習中は自分のためのコメントを書いてよい

Javaを学び始めたばかりのころは、コメントを上手に書かなければならないと考えすぎなくて大丈夫です。

まずは、自分があとで見返したときに分かるコメントを書けば十分です。

たとえば、次のような短いコメントで問題ありません。

// Java修行の開始メッセージを表示するプログラム

このコメントは、とても素直で分かりやすい書き方です。

難しい専門用語を使わなくても、プログラムの目的が伝われば十分です。

コメントを書くことで、ただコードを入力するだけでなく、意味を考えながら学ぶ習慣が身につきます。

コメントは読みやすいコードへの第一歩

Javaコードでは、正しく動くことがもちろん大切です。

しかし、それと同じくらい、人が読んで理解しやすいことも大切です。
コメントは、その読みやすさを作るための身近な工夫です。

Sample1.javaの先頭にあるコメントは、たった1行です。

// Java修行の開始メッセージを表示するプログラム

しかし、この1行があるだけで、プログラム全体の役割が分かりやすくなります。

これからJavaのコードが長くなるほど、コメントの大切さは増していきます。

まずは Sample1.java のような基本的なコードの中で、コメントは人のために書く説明であり、コンピュータはそれを実行しない、という仕組みをしっかり押さえておきましょう。