【Javaリファクタリング】綺麗なコメントの書き方

Javaのコメントは、1行の場合「//」、複数行の場合「/*」と「*/」になりますが、人によって結構コメントの記述法がバラバラになりがちですよね。

一行コメント(//)について

知っている方も多いと思いますが、Eclipseで言えば、「Ctrl + /」がショートカットになります。

 利用場面

・基本的には、メソッド内の処理のまとまりや、フィールドの前等に記述したりすることが多いです。

 

複数行コメント(/* ～ */)について

利用場面

・クラスやメソッド等のプログラムの説明を書くときに使う。

JavaDocコメント(/** ～ */)について

JavaDocとは、「Javaドキュメンテーションコメント」のことです。

	/**
	 * int型の数値を1加算して返します。
	 * @param 加算対象の数値(int型)
	 * @return 加算後の数値(int型）
	 * @author t.taro
	 * @version 1.0
	 */
	public int methodA(int num) {
	    num++;
	    return num;
	}

普通の複数行コメントと違って、先頭のアスタリスクが二つになります。

Eclipseでは、Alt+Shift+Jでがショートカットになります。
また、下記のようなアノテーションタグを使ってコメントを作ります。

使用できるタグ	説明
@param	パラメータ(引数）
@return	戻り値
@author	プログラム作成者
@throw	投げられる例外
@version	プログラムのバージョン

JavaDoc生成後のHTMLの出力結果としては下記のようになります。(Eclipseで、「プロジェクト」→「JavaDoc生成」を選ぶと自動生成できます。）

なお、プログラムのバージョンの付け方に関しては下記の記事を参考にされて下さい。

【プログラミング】バージョンの付け方

TODOコメント(//TODO)について

利用場面

・作りかけや、未実装の処理に使用するコメント（Eclipseでは、TODOを一覧化する機能があります。）

	public void methodB() {
		//TODO 未実装メソッドです。
	}

コメントのメリット、デメリット

コメントは、メリットばかりに思えますが、一概にそうではありません。

誤ったコメントが付けられている場合は、かえって開発者を混乱させます。

ソースコード修正後に、コメントも修正しなければならないが、されていないケースがある場合もあります。

不要なコメントは、できるだけ避けるようにしましょう。

必要なコメントの例

そのソースコードの存在意義が書かれたコメント

不要なコメントの例

一行一行実況中継しているコメント（ソースを読めば分かるため）

まとめ

色々なコメントの書き方について解説しましたが、できれば可読性を考慮すると、メソッド名や固定値、変数名の工夫、デザインパターンの活用等をして「そのプログラムが何をやっているか」わかるようになることが理想的なプログラムといえるので、最終的にはコメントはJavaDocコメントのみという形を目指しましょう。