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コメントのみという形を目指しましょう。
この記事へのコメントはありません。