Javaのコメントの書き方について書いています。
最初にコメントの書き方について記載しています、その後にJavadocについて簡単に説明しています。
載せているコードについては、OpenJDKのバージョン19で動作を確認しました。
コメントの書き方
コメントは書いたプログラムに説明を書くことができる機能になります。
プログラムのビルド時に無視される説明をつけておくことができます。
例えば、下記のようにコメントすることができます。
// forで5回ループする
for (int i = 0; i < 5; i++) {
System.out.println("hello.");
}
for文の上にコメントをつけました。
スラッシュ(/)をふたつ書いた後は、行末までプログラムで実行されず無視されるので、説明を書けます。
プログラムの命令文の後に書くこともできます。
System.out.println("hello."); // helloと出力する
このように命令文の後にスラッシュを書いて、コメントすることもできます。
ここでは、例として簡単な処理にコメントをつけました。
実際は誰でもみて分かりそうなところにはつけずに、複雑な処理に対して付けていくようにしましょう。
できるだけコメントを書かないでも済むような、わかりやすいコードを書いておくことも大切かと思います。
複数行コメントについて
上記は1行のみのコメントでしたが、複数行コメントすることもできます。
例えば、下記のように書くことができます。
/**
* ２つの引数を足して出力する.
* @param a 数値1
* @param b 数値2
*/
public void sum(int a, int b) {
System.out.println(a + b);
}
関数の先頭に複数行コメントをつけました。
このように関数の先頭や、クラスの先頭にコメントをつけておくことはよくあります。
一目で何をする関数か、どんなクラスがわかるので良いですね。
スラッシュとアスタリスク(/*)から始まって、アスタリスクとスラッシュ(*/)までがコメントになります。
改行してもいいですし、1行でも使うことができます。
/* Test */
int test = 0;
ですが面倒なので、1行の場合には、先ほどのスラッシュを2つ付けるコメントを使う方が良いです。
Javadocについて
Javadocは、JavaのソースコードからAPI仕様書を生成できるコマンドです。
プログラムを作成するときに、Javadocのタグにしたがってコメントしておくことにより、みやすい仕様書をコマンドで作ってくれます。
先ほどの@paramはJavadocで使用できるタグになります。
@paramを書いた後には、パラメータ名を付けて、その後に説明をつけます。
例えば、クラスを下記のように作成します。
package com.codelikes.poc.java.BasicTests;
/**
* コメントをテストするクラス.
* @author yasuaki
* @version 1.0
*/
public class CommentTest {
/**
* コンストラクタ.
*/
public CommentTest () {
}
/**
* メイン処理.
*/
public void exec() {
// forで5回ループする
for (int i = 0; i < 5; i++) {
System.out.println("hello.");
}
this.sum(13, 20);
}
/**
* ２つの引数を足して出力する.
* @param a 数値1
* @param b 数値2
*/
public void sum(int a, int b) {
System.out.println(a + b);
}
}
javadocコマンドを実行すると、htmlファイルが作られます。
開くと下記のように、javadocでつけたコメントに応じて、わかりやすい仕様書ができています。
javadocで出来たドキュメント
Javadocの詳細については、公式ドキュメントのこちらに詳細があるので確認してみてください。
Javaコメントの書き方まとめ
今回はJavaでコメントを書く方法について紹介しました。
記事の内容をまとめると下記のようになります。
・Javaで複数行コメントするときには、`/*`で始めて`*/`で閉じる。
・Javadocにしたがってコメントを書くことで、javadocコマンドを使って仕様書を作ることができる。
処理がわかりにくくなってしまった箇所には、コメントをつけておくと良いです。
また、Javadocにしたがってコメントを書いておくことで、見やすいコメントをつけることができました。
コメント