javadocコメントというのは、
/**
*
*/ものすごく簡単に言うと、これです。
クラスやメソッドの上によくあるやつですね。
絶対に書いた方がいいです。
これを書いているか書いていないかで、
コードの読みやすさが全然違います。
さらにjavadocコメントを書くことで、
プログラムの仕様書にもなります。
今回はjavadocコメントの使い方などを
紹介していきます。
javadocコメントを書くとどうなるか
一言で言うと、コードが読みやすくなります。
なぜか。
「Hello World！！」
を表示するプログラムを例に説明しましょう。
javadocコメントサンプル
めちゃちゃ簡単な例です。
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
/**
* Spring起動時に走リまーす
* @author 著者でーす
*
*/
@SpringBootApplication
public class HelloWorldApplication {
public static void main(String[] args) {
SpringApplication.run(HelloWorldApplication.class, args);
var HelloWorld = new HelloWorld();
String helloWorld = HelloWorld.SetHelloWorld();
System.out.println(helloWorld);
}
}package com.example.demo;
/**
* Hello World作りまーす
* @author 著者でーす
*
*/
public class HelloWorld {
/**
* Hello World!!の文字列を作成
* @return Hello World!!
*/
public String SetHelloWorld() {
String helloWorld = "";
helloWorld += "Hello";
helloWorld += " ";
helloWorld += "World!!";
return helloWorld;
}
}このようなjavadocコメントが書いてある、
「Hello World!!」と表示されるコードがあったとします。
mainメソッドを追っていた時、
18行目の
String helloWorld = HelloWorld.SetHelloWorld();の上に差し掛かったとします。
この時、
このメソッドはどういうメソッドなのだろうと、
メソッドの上にポインターを合わせると、
このような感じに、
メソッドの説明や返り値、返り値の型などを表示してくれます。
このメソッドは、比較的わかりやすいメソッドなので、
そこまでありがたみを、感じにくいかもしれませんが、
現場に行くと、メソッドが複雑化してしまうことや
修正で他人が書いたコードを読まないといけない時が必ずあります。
そんな時に、javadocコメントが
あるのと無いのとでは大きな差です。
javadocコメントが無いサンプル
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class HelloWorldApplication {
public static void main(String[] args) {
SpringApplication.run(HelloWorldApplication.class, args);
var HelloWorld = new HelloWorld();
String helloWorld = HelloWorld.SetHelloWorld();
System.out.println(helloWorld);
}
}package com.example.demo;
public class HelloWorld {
public String SetHelloWorld() {
String helloWorld = "";
helloWorld += "Hello";
helloWorld += " ";
helloWorld += "World!!";
return helloWorld;
}
}この時、同様に、
String helloWorld = HelloWorld.SetHelloWorld();ここにカーソルを合わせてみます。
このように、javadocコメントが無い場合、
返り値の方しか表示されません。
これだと、このメソッドで何をしているのかが、
すぐには分かりにくいです。
javadocの生成（Eclipse使用）
javadocコメントは、書いていると
そのソースの仕様書のようなものをhtmlファイルで生成することができます。
サンプル↓
上記のクラス列はリンクとなっており、
クリックして中を見ることができます。
そして、説明欄などにコードで書いておいたjavadocコメントが反映されます。
javadocコメントを書いておくだけで、簡単な仕様書を作成することができるのです。
実際の動作が見たい方は、以下のGitHubにコードとhtmlファイルを載せているので
こちらでもご確認ください。
生成手順
対象プロジェクトを右クリック→エクスポート
Javadoc選択
設定をしていき、完了をクリック
「次の可視性を持つメンバーのjavadocを生成」では、どのレベルでjavadocを生成するかを設定します。
説明については選択するとEclipseはすぐ下に出てくるのでそこを見ましょう。
「標準ドックレットを使用」の「宛先」で、javadocの出力先を指定します。
デフォルトではsrcと同じ階層にdocというディレクトリを作成し、
そこへ出力します。
ここでオプションを設定します。お好きにどーぞ。
追加のjavadocオプションで文字コードなどを指定し、
完了まで押すと、宛先で指定していたところにjavadocが生成されています。
ここでのオプションは、コマンドなどでjavadocを作成するときのオプションと同等です。
この中のindex.htmlをブラウザで開くと、始めに紹介した画面へと遷移します。
このようにjavadocコメントを書くかどうかで
コードの読みやすさは全然違います。
javadcコメントは必須で書きましょう！！
また、javadocコメントにはさまざまな種類があります。
よければこちらの記事もご覧ください。
参考サイト
