【Java】プログラミングでのコメントの書き方とJavadocコメントから APIリファレンスを生成方法を詳しく解説！

こんにちは。駆け出しプログラマーの松倉です！

ここでは、Java のコメントの種類と書き方ついて紹介・解説します。

プログラミング未経験の方、Javaについて勉強している方、これから勉強したいと思っている方の参考になれば幸いです！ 

関連記事リンク：【Java】開発者が読むべき標準ドキュメント、【Java】標準入出力とは？書式指定のやり方は？Scannerクラスとは？　使い方を解説！、【Java】アノテーションの役割とは？3つのタイプと標準アノテーションを紹介

コメントとは?

コメントとはプログラムを読む人向けの説明です。

プログラム実行時に無視される記述であり、あってもなくてもプログラムの動きに変わりはありません。

しかし後からプログラム内容の確認や、自分の作ったプログラムを他の人に見てもらうときに説明があるとわかりやすくなります。

またプログラムの実行が無視されるということは、動作検証等をするためにプログラムの一部を敢えて動かなくするという使い方もできます。

コメントにはひらがな、カタカナ漢字、英数字と全てのものが使うことができ、改行で複数行にわたることも可能です。

この記事ではコメントについて以下のことを紹介・解説を行います。

• コメントの種類
• コメントの書き方
• Javadocコメント

コメントの種類

Java ではコメントの記述方法として「1行コメント」、「複数行コメント」、「Javadocコメント」の 3つの方法が用意されています。

書き方についても少しずつ違いがあるので、合わせて確認しましょう。

※Javadocコメントについては後述します。

1行コメント

1行で書く場合は「//」のようにスラッシュ記号を 2つ書くことで、その行をコメントにすることができます。

// 計算結果を表示する。

複数行コメント

複数行で書く場合は「/*」と「*/」の間がコメントになります。

「/*」がコメントの開始で、「*/」がコメントの終了を意味します。

/*
複数行の
コメント
*/

コメントは読み手に伝えたいことがある場合や、可読性の向上のために使われます。

不要なコメントはプログラムが余計に読みずらくなり、逆効果になる場合があるため注意しましょう。

Javadocコメント

Javadocは一定の規則に従って書かれた Javaのソースコードから、クラスの概要やメソッドの概要などの HTML形式の APIリファレンス(仕様書)を生成することができます。

Javadocに対応した形でコメントを記述しておくだけで、即座にクラスやメソッドの仕様書を作成できるため非常に便利です。

Javadocコメントを書く場合は「/**」と「*/」の間がコメントになります。

Javadoc の書き方

/** Javadoc */

/**
 * Javadoc
 */

※Javaのコメントは「/*」が開始で「*/」が終了と書き方が似ているため、Javadocコメントと混同しないように気をつけましょう。

Javadocコメントの中は大きく分けると「説明文」と「タグセクション」の 2つに分類することが出来ます。

説明文はクラスやメソッドなどに対して簡潔に説明した文となります。

説明文は HTML文として解釈されるため単に別の行に記述しても改行はされずに表示されます。

Javadocの中では javadocタグが用意されています。

タグセクションは先頭の文字が「@」で始まる特殊な記号として扱われ、それぞれ下記のような意味を持ちます。

• @version：使用しているバージョン
• @author：開発者名
• @exception(@throws)：メソッドが投げる例外クラスとその説明
• @param：メソッドの引数名と引数の概要
• @return：メソッドの戻り値

タグセクションは 1つのコメントの中に複数の種類を同時に記述することが出来ます。

/**
 *  このクラスはJavadoc説明用のクラスです。
 *  複数行に渡って記述することが可能です。
 *  @version 2.0
 *  @param string 名前
 *  @param int 年齢
 */

タグセクションが記述された後に「説明文」を記述することはできないので注意しましょう。

※補足

Eclipseで Javadocを記述する場合、コメントを挿入したいメソッドやフィールドの宣言文上にカーソルを置き、下記のショートカットキーを使用することで簡単にフォーマットを追加することができます。

Windows：Alt + Shift + J

Mac：option + command + J

それでは Javadocコメントから APIリファレンス生成の手順を解説します。

まず以下のようなサンプルコードを書きましょう。

/**
 * Javadoc説明用クラス
 * @author forward-soft
 * @version 3.0
 */
public class Sample {
	/** 幅 */
	private int w;

	/** 高さ */
	private int h;

	/** コンストラクタ */
	Sample() {
		w = 0;
		h = 0;
	}

	/**
	 * サイズ設定
	 * @param width 幅
	 * @param height 高さ
	 */
	public void setSize(int width, int height) {
		w = width;
		h = height;
	}

	/**
	 * 幅の取得
	 * @return 幅
	 */
	public int getWidth() {
		return w;
	}

	/**
	 * 高さの取得
	 * @return 高さ
	 */
	public int getHeight() {
		return h;
	}
}

上記のように書いたソースコードを名前を付けて保存しましょう。

Eclipseのメニューから「ファイル」＞「エクスポート」をクリックしてみましょう。

「Java」＞「Javadoc」をクリックし、「次へ」をクリックします。

「Javadocコマンド」に Javadocが記述されていることを確認し、空欄になっている場合は「構成」ボタンを押してJavadocを指定してください。

「Javadocが生成される型の選択(T):」でJavadocを生成するファイルを選択し、「完了」をクリックします。

「完了」をクリックするとプロジェクト内にHTMLファイルが生成されます。

実行したディレクトリ内に「doc」と言うディレクトリが作成され、中には数多くのHTMLファイルが作成されています。

この中の「index.html」ファイルを右クリックし「Web ブラウザー」で開いて下さい。

「Web ブラウザー」を開くとドキュメントが作成されていることが確認できます。

Webブラウザ内の「パッケージ」＞「クラス概要」の中の「Sample」をクリックしてページを移動してみましょう。

ソースコードに書かれたコメントを元にクラスやメソッドの仕様書が作成されていることが確認できました。

書き方を間違えていると Javadoc が出力されません。

Javadoc はそのまま仕様書として使うことができるので、漏れがあった場合は書き方を見直してみましょう。

コメントの書き方

それぞれのコメントの書き方を紹介します。

1行コメント

1行コメントの書き方をサンプルコードで確認しましょう。

public class Sample1 {
	public static void main(String[] args) {
		// ディスプレイに表示するためのメソッド
		System.out.println("Hello World");
	}
}

実行結果：

Hello World

コメントがプログラムの実行には何の影響も与えていないことが確認出来ました。

複数行コメント

複数行のコメントの書き方をサンプルコードで確認しましょう。

public class Sample2 {
	public static void main(String[] args) {
		/*
		ディスプレイに
		表示するためのメソッド
		*/
		System.out.println("Hello World");
	}
}

実行結果：

Hello World

改行コメントの記述を確認出来ました。

Javadocコメント

Javadocコメントの書き方をサンプルコードで確認しましょう。

/**
 * @author forward-soft
 * @version 0.0.1
 */

/** Javadoc解説用のメインクラス */
public class Sample3 {
	/**
	 * mainメソッド
	 * @param args 使用しない
	 */
	public static void main(String[] args) {
		// ディスプレイに表示するためのメソッド
		System.out.println("Hello World");
	}
}

実行結果：

Hello World

Javadocコメントの使い方が確認出来ました。

まとめ

今回はコメントについて解説しました。

コメントを記入しておくと後からプログラムの内容を確認したり、読み手にわかりやすくなります。

また動作検証等をするためにプログラムの一部を敢えて動かなくするという使い方もできます。

プログラムを書くとコメントは頻繁に使われるものなので使い方は自然と覚えられると思います。

上手に使えるとプログラムの可読性の向上につながります。

Javadocのコメントの書き方についても記述しているので忘れた方はまた読み返しに来てください！

関連記事リンク：【Java】開発者が読むべき標準ドキュメント、【Java】標準入出力とは？書式指定のやり方は？Scannerクラスとは？　使い方を解説！、【Java】アノテーションの役割とは？3つのタイプと標準アノテーションを紹介