Javaプログラムのコメント―書き方や注意点など

Javaプログラムの書き方や注意点など。Javaプログラムのコメントについてまとめています。

▲記事トップへ

Javaプログラムのコメント

Javaのプログラムには次のようなコメントがあります。

「//」から行の終わりまではコメント
プログラム中に「//」とダブルスラッシュを記述した場合、「//」から行の終わりまでがコメントになります。
「/*」と「*/」で囲んだ範囲はコメント
プログラム中に「/*」と「*/」で囲んだ範囲はコメントになります。
「/**」と「*/」で囲んだものはJavadocコメント
クラスやメソッド、メソッドの外の変数の上部に「/**」と「*/」で囲んだコメントはJavadocコメントといいます。コメントがJavadocという仕様書を生成する際に使われる記述となります。javadocコマンドで生成します。
「//TODO」から行の終わりまではTODOコメント
「//TODO」から行の終わりまではTODOコメントといいます。未実装や作りかけなどの覚書に使うコメントです。 Eclipseなどの開発ツールでこのTODOコメントを抽出する機能があり、効率よく作業するためにあります。

以下ではこれらのJavaのプログラムコメントの書き方、注意点をまとめています。

Javaのプログラムコメントの書き方

サンプルコードを示しながらJavaのプログラムコメントの書き方を説明していきます。

「//」から行の終わりまではコメント

プログラム中に「//」とダブルスラッシュを書いた場合、「//」から行の終わりまでがコメントになります。

Javaのコンパイラは、「//」という記号からあとの文字を無視します。「//」記号の後ろには、プログラムの実行とは直接関係ないメモなどを書き残すことができます。

以下のサンプルコードはこのプログラムコメントの書き方の例です。

class Sample {
 	public static void main(String args[]) {
 		System.out.println("Hello World!"); //最初のプログラムは伝統的にHello World!!を出力します。
 	}
}

「//最初のプログラムは伝統的にHello World!!を出力します。」の部分がコメントになります。

「/」と「/」で囲んだ範囲はコメント

プログラム中に「/*」と「*/」で囲んだ範囲はコメントになります。

「//」以外に「/* ～ */」という記号を使用することもできます。このコメントの場合は、「/*」「*/」で囲まれた部分が、すべてコメントになります。

以下のサンプルコードはこのプログラムコメントの書き方の例です。

class Sample {
 	public static void main(String args[]) {
 		/*
 		最初のプログラムは伝統的にHello World!!を出力します。
 		*/
 		System.out.println("Hello World!");
 	}
}

「/* 最初のプログラムは伝統的にHello World!!を出力します。*/」の部分がコメントになります。

「/**」と「*/」で囲んだものはJavadocコメント

クラスやメソッド、メソッドの外の変数の上部に「/**」と「*/」で囲んだコメントはJavadocコメントといいます。コメントがJavadocという仕様書を生成する際に使われる記述となります。javadocコマンドで生成します。

以下のサンプルコードはこのプログラムコメントの書き方の例です。

/**
 * サンプルクラス
 * サンプルとして伝統的なHello World!!の文を扱うクラスです。
 * @author zealseeds
 */
class Sample {
 	public static void main(String args[]) {
 		System.out.println("Hello World!");
 	}
}

「/**」と「*/」で囲んだ部分がJavadocコメントになります。「@」で始まる「@author ＜著者＞」のようなJavadoc用の機能がコメントの中に書くこともできます。

「//TODO」から行の終わりまではTODOコメント

「//TODO」から行の終わりまではTODOコメントといいます。未実装や作りかけなどの覚書に使うコメントです。 Eclipseなどの開発ツールでこのTODOコメントを抽出する機能があり、効率よく作業するためにあります。

以下のサンプルコードはこのプログラムコメントの書き方の例です。

class Sample {
 	public static void main(String args[]) {
 		//TODO 今度もっと別の表示に変更する。
 		System.out.println("Hello World!");
 	}
}

「//TODO 今度もっと別の表示に変更する。」の部分がTODOコメントになります。

プログラムコメントの注意点

プログラムコメントの注意をまとめます。

必要なコメントは適切なところに残すよう努力する

コードを書いているときは、覚えていても直ぐに忘れます。未完成部分など将来の自分や共同開発者のために補足説明を残しておくべきです。

注意点としては、コメントがあればあるほど記述量が多くなり、読まなくてはならない量が増えます。つまり、可読性がわるくなり、後で読みなおすときに時間がかかります。コメントが無くても分かるようになってる方がうれしいです。

後で詳細は触れますが、必ずしもコメントをプログラムに書かなくてもいいかもです。

コメントは極力書かないように努力する

上述の通り、コメントは可読性を下げる要因にもなります。以下のような考え方もあると思いますので参考にしてもらえればと思います。

プログラム自体の書き方

プログラム自体の書き方を工夫すれば、コメントが不要になるかもです。

メソッドなど名前の付け方
Javaなどオブジェクト指向のプログラミングでは、習慣的なルールとして英語の動詞＋名詞のように記述して、何をするかメソッド名を見ればわかるように記述します。
マジックナンバーの置き換え
ただ単に100という値を使うと何の100？となります。このような値をマジックナンバーといいますが、MAX_OUTPUT_SIZE=100というように定数に100という値を設定して使うようにすれば、最大出力サイズは100とわかり、わざわざコメントで「100//最大出力サイズ」と書かなくてすみます。
デザインパターンの適用
一般に知られているデザインパターンを適用すれば、どういう仕様か、プログラムすら見なくても想像しやすいです。

仕様の残し方

仕様の残し方を工夫すれば、コメントが不要になるかもです。

テストプログラムの導入
だいたいプログラムは書いて、直して、動かしてを何回か繰り返して作ると思います。つくりながら動かして正しい挙動をチェックするテストプログラムも作っておくと便利です。そのチェックプログラムにはプログラムの挙動が定義されていますので、仕様書みたいなものです。これがあれば、後で仕様をチェック出来きるのでコメントが減ると思います。
バージョン管理やタスク管理システムの活用
バージョン管理ソフトを使えば修正履歴が残りますので、修正履歴のコメントはいらなくなります。また、タスク管理とバージョン管理が連携するシステムを使えば、仕様調整や課題事項などのコメントもシステムの方に集約されて便利です。プログラムに仕様調整内容や課題事項をわざわざ残さなくてよくなると思います。

まだまだ沢山あったり、ずれたことを書いているかもしれませんが、何が言いたいかというと、「コメントの少ないプログラムが実現できる＝高度なテクニックがある」といいたいわけです。はじめはコメントがたくさん必要ですが、レベルアップして、高度化して、コメントゼロのプログラムを目指したいです。