Javaでコメントを書く３つの方法！プロを目指すならコメントもしっかり書こう

Javaを始めとするプログラミング言語には、
ソースコードで行っている処理に関する説明をコメントで記述できます。コメントで書かれた部分は、コンパイル時には取り除かれるため、プログラムの実行に一切の影響も与えません。

この記事では、Java でのコメントの記述方法として「行コメント」「ブロックコメント」「Javadoc」の３つのコメントの書き方を解説していきます。

コメントは、ソースコードに記述された処理を理解しやすくする重要な役割があります。この記事を読んで、コメントを是非記述するようにしていきましょう。

行コメント

行コメントは、// を使った単一行のコメントです。ソースコードの中で // を記述した箇所から、その行の最後までがコメントになります。

// 単一行のコメントです

行コメントの// は、行の先頭に記述すると、その行全体がコメントになります。また、処理を行っている行の右側に// を書くと、その箇所から行の末尾までがコメントになります。

具体的な行コメントの書き方は、次のサンプルコードを確認してください。

// 一行コメント
int a = 0;


for (int i = 1; i <= 10; i++){
  a = a + i;  // 数値を加算する
}

if (a == 55){

}

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

ブロックコメントは、 /* と */ で囲った部分を一括でコメントアウトします。複数行にまたいでコメント化できるため、ブロックコメントまたは、複数行コメントとも呼ばれます。

/* ブロックコメント */ 


/* 
ブロックコメント 
ブロックコメント
ブロックコメント
*/ 

Javadoc コメント

Javadoc とは、Javaソースコードに記述されたコメントからドキュメントを生成するツールです。Javadoc コメントは、このJavadoc ツールでドキュメントを生成するための書式で書かれたコメントを指します。

Javadocコメントは/**から*/までに書かれた部分がJavadocの対象となります。ブロックコメントの/* コメント */と似ていますが、先頭のアスタリスクが２つある違いに注意しましょう。

/**
  javadocコメント
  javadocコメント
*/

ポテパンダの一言メモ

Java の開発現場では、Javadoc ツールでドキュメントを生成しない場合でも、この Javadoc コメントを使用してクラスやメソッドのコメントを付与するのが一般的です。

この他にも @paramやreturnなどのタグを使って、引数や戻り値の情報も Javadocコメントでは記述します。具体的にクラスやメソッドコメントの書き方を見てみましょう。

クラスの Javadoc コメント

クラスの Javadoc コメントには、そのクラスの目的や使用上の注意点など、クラスの概要を記述していきます。クラスのメソッドに対するコメントは、メソッド宣言部の Javadoc コメントに記述するため、あくまでクラスの Javadoc コメントには、クラスの概要を記述します。

/**
 商品データの検索を行うクラス。
 */
public class ProductSearch {
}

開発プロジェクトによっては、クラスの Javadoc コメントに、クラスの作成者（@author）やバージョン（@version）なども記述します。

/**
* 商品データの検索を行うクラス。
* @author　Yamada Taro
* @version　1.0.0
*/
public class ProductSearch {
}

また、クラスの使用方法に注意点などがある場合は、サンプルコードを添えて説明すると分かりやすいコメントになります。Javadoc コメントにサンプルコードをのセル場合、HTMLタグである <blockquote>および<pre>の中にコードを記述します。

/**
* 商品データの検索を行うクラス。
* <p>
* このクラスを使用する時は、直接 new をせずに、getInstance() メソッドを使用します。
* <blockquote><pre>
*     ProductSearch search = ProductSearch.getInstance();
* </pre></blockquote><p>
*/
public class ProductSearch {

  public static Product getInstance() {
      //処理
  }
}

メソッドの Javadoc コメント

メソッドの Javadocコメントには、そのメソッドの役割やパラメータの情報、使用することで得られる結果（戻り値）を記述します。また使用する時の条件や、発生する例外の種類や発生条件など、そのメソッドの概要を制約条件を分かり易く簡潔に記述します。

逆に、メソッド内で行われている処理の詳細はあまり詳細に記述しません。あくまで、そのメソッドの利用者の立場に立った、入力と出力の説明にフォーカスを当てて Javadoc コメントを記述します。

具体的に、メソッドの Javadoc コメントのサンプルを見てみましょう。

/**
* 指定した商品IDで商品マスタを検索し、該当する商品データを返す
* @param　productId 商品ID
* @return　商品IDに該当する商品データ。該当する商品が存在しない場合は null
*/
public Product getProduct(String productId){
    //処理
}

どこまで詳細に Javadoc コメントを書けばよいのか？

コメントを記述する時に、どこまで詳細に内容を記述するべきかを悩む場合もあるでしょう。

参考までに、Javaでもっともよく使われる Stringクラスの Javadoc コメントは次のようになっています。クラスの概要や使用方法のサンプルコードなど非常に細かく分かりやすくコメントが記述されています。

/**
 * The {@code String} class represents character strings. All
 * string literals in Java programs, such as {@code "abc"}, are
 * implemented as instances of this class.
 * <p>
 * Strings are constant; their values cannot be changed after they
 * are created. String buffers support mutable strings.
 * Because String objects are immutable they can be shared. For example:
 * <blockquote><pre>
 *     String str = "abc";
 * </pre></blockquote><p>
 * is equivalent to:
 * <blockquote><pre>
 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 * </pre></blockquote><p>
 * Here are some more examples of how strings can be used:
 * <blockquote><pre>
 *     System.out.println("abc");
 *     String cde = "cde";
 *     System.out.println("abc" + cde);
 *     String c = "abc".substring(2, 3);
 *     String d = cde.substring(1, 2);
 * </pre></blockquote>
 * <p>
 * 〜 以降省略（この後も数十行におよぶ詳細なコメントが続きます） 〜
 */
 public final class String {

Stringクラスは全世界の人が参照するため、ここまで詳細にコメントが記述されていますが、個別システムの開発ソースであれば、ここまでの詳細なコメントは必要ないでしょう。

まとめ

行コメント、ブロックコメント、Javadocコメントの書き方を紹介してきました。

基本的は、クラスやメソッドの利用者の立場に立った分かりやすい Javadocコメントを記述することを目指しましょう。