【Java】コメント

前回はJavaの命名規則について書きましたが、今回はコメントについて。
Javaには主に3種類のコメントがあります。
それぞれ次のような役割です。

ドキュメンテーションコメント （Javadocコメント）	/** ～ */ で囲み、クラス，インタフェース，コンストラクタ，メソッド，フィールドについて記述するコメント。 Javadocにより処理された外部ドキュメントを生成可能。
ブロックコメント	/* ～ */ で囲み、ファイル，メソッド，データ構造，およびアルゴリズムについて記述するコメント。 Javadocコメントと誤認しやすいため、余り使用をお勧めしない。
単一行コメント	コードの概要などを記述するコメント。 // で始まる1行をコメントアウトする。

それぞれのコメントの例も書いてみます。
まずはJavadocコメント。

/**
 * 設定されている画面消灯までの時間をミリ秒で返却する。
 * 取得できない場合は30000ミリ秒を返却する。
 *
 * @return 画面消灯までの時間
 */
public String getOffScreenSetting() {
 return Settings.System.getString(mContext.getContentResolver(), Settings.System.SCREEN_OFF_TIMEOUT);
}

/** 30000ミリ秒（デフォルトの時間として使用） */
private static final String DEFAULT_MS = "30000";

主にメソッドや定数名に使用します。
Javadocコメントの大きな特徴として、Javadocを生成できます。
上記のコメントだと次のように表示されます。

また、外部出力も可能ですのでプロジェクトでの管理等にも利用できます。
（詳細は本家Javadocを参照して下さいね）

ブロックコメントはsirocoは余り推奨しないので割愛。

単一行コメントは実際の開発で一番良く使う事になると思います。
次のような感じで使います。

if (android.os.Build.VERSION.SDK_INT == 17) {
 // Android4.2(API level17)の場合は"-1"が非表示の値でない？？
    // "-1"の代わりにintの最大値を設定
 NOT_OFF_SCREEN = Integer.MAX_VALUE;
 NOT_OFF_SCREEN_STR = String.valueOf(Integer.MAX_VALUE);
} else {
 NOT_OFF_SCREEN = -1;
 NOT_OFF_SCREEN_STR = "-1";
}

上記の例は余り良い例ではないですが、コードを見ただけでは分かりづらい所に補足としてコメントを入れるのが良いでしょう。

本来であればコードだけで処理の内容が誰でも理解できるのが理想です。
ですが、実際はそうはいきません。
わかりづらいところには適当にコメントをいれて可読性を高めましょう。

コメントについては以上です。