JavaのコメントとJavaDocの書き方!複数行のコメントアウトも解説。

JavaのコメントとJavaDocの書き方!複数行のコメントアウトも解説。

この記事では、Javaにおけるコメントの種類や書き方。また、Javaの長所のひとつであるJavaDocについて解説する。

どのプログラミング言語を習得するかに依らず、コメントはプログラミングを始めてすぐに使用するように機能のひとつだろう。

使用しているIDEのショートカットとともに早いうちに覚えてしまおう!

Javaのコメントについて

コメントはJavaのソースコード内に記述される、実行結果に影響を及ばさない文字列だ。

既存のソースコードの一部をコメント化することをコメントアウトするという。

コメントアウトされたコードは、コードを実行する際には無視される。

EclipseやIntellijではコメントアウトのためのショートカットがあらかじめ割り当てられている。よく使用することになるので覚えておくようにしておこう。

この記事では、コメントとともに使われるIDEの機能であるTODOやJavaDocといった便利な機能を紹介したい。

コメントアウトの種類

では、Javaのコメントには二つの記述方法がある。

HTMLやCSSにもそれぞれ独自のコメントアウトの記述方法があるので、それぞれ覚えるようにする。

一行ずつのコメントアウト

コードを一行ずつコメントアウトしたい時はこの記述を使用する。

この場合はコードの先頭にスラッシュを2つ付ける。

// System.out.println("この文字は出力されない。");

複数行のコメントアウト

複数行のコードをまとめてコメントアウトしたい場合はこの記述を使用する。

コメントアウトしたい範囲の先頭に/**を付け、終わりに*/を記述する。

囲まれている範囲のすべてのコードはコメントアウトされている。

/** int number = 7;
System.out.println(++number);
System.out.println(number++);
System.out.println(number--);
System.out.println(--number); */

TODOとFIXME

コメントと併せてよく使われるのがTODOとFIXMEだ。

これらはコード内にメモを残すような感覚で使用できる。職場によってはTODOやFIXMEに関する使用ルールがある場合もあるのでルールに則って使用するようにしよう。

  • TODO 作業が残っている箇所のためのメモ。
  • FIXME 修正の必要がある箇所のためのメモ。

TODOやFIXMEを付けた箇所はこのように一覧で確認することができる。

IntellijnのTODOの例

JavaDocの使い方

次にJavaの重要な機能のひとつであるJavaDocについて説明したい。

JavaDocを作成する

JavaDocの記述方法は簡単だ。

JavaDocの内容として書き出したいフィールドやメソッドのうえにカーソルをおき、/**と入力してENTERを押せば、自動で引数や返り値を含む雛形が作成される。あとは必要に応じて、フィールドやメソッドの説明を記述しよう。

/**
 * このメソッドは苗字と名前をセットにして返します。
 *
 * @param firstName
 * @param lastName
 * @return
 *
 * @since Ver 1.2.1
 */
public static String exampleMethod(String firstName, String lastName) {
    return firstName + " " + lastName;
}

このようにして記述したJavaDocは、メソッドにカーソルを合わせることによってIDE上でも素早く確認することができる。

JavaDocをHTMLとして書き出す

記述したJavaDocは簡単にHTMLファイルとして出力することができる。

例としてIntellijでは次のような画面で出力するファイルの内容を設定することができる。

HTMLファイルとして書き出したJavaDocはこのようにブラウザーで閲覧することができる。

Javaのプログラマであればこのようなフォーマットで記述されたドキュメントをインターネット上で目にしたことがあるだろう。