javadocタグとは、javadocコメントで使用される
アノテーションです。
javadocコメントとは何かを知りたい方は、
先にこちらの記事をお読みください。
今回は、javadocタグの中でも、
よく使うタグの種類とその使い方を
タグごとに説明していこうと思います。
タグ一覧
| タグ | 意味 | サンプル |
|---|---|---|
| @author | 作成者 | @author Takumi |
| @return | 戻り値の説明 | @return HelloWorldの文字列 |
| @throws | 例外 | @throws NullPointerException |
| @see | 関連項目 | @see <a href=”https://tsuka-ma.com/javadoctag/“>javadocタグ一覧</a> |
| {@link} | 参照先のリンク | {@link HelloWorld#SetHelloWorld()} |
| {@literal} | そのままの文字を表示 | {@literal a < b}の”<“などのjavadoc内で認識されない文字を書くとき |
| {@code} | <code>{@literal}</code> | {@code List<String>}などコードを書きたいとき |
@author
作成者情報です。
意外と重要です。
サンプルコード
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
/**
* @author Takumi
*
*/
@SpringBootApplication
public class HelloWorldApplication {
public static void main(String[] args) {
SpringApplication.run(HelloWorldApplication.class, args);
System.out.println("Hello World!!");
}
}表示例
現場では、他人の書いたコードを修正する場合が多々あります。
その際に、作成者が誰なのかが書いてあるか、書いていないかで
効率が少し違います。
書いてない場合は、
わからないコードが出てきた時に、
「あーわからん。。。誰だこのコード書いたの。」
タスク一覧などで調べる。。。
「ああ、あの人か。スラック飛ばそ。」
と、一手間増えてしまいます。
逆に、作成者情報がコードに書いてあれば一瞬ですね。
このタグは、クラスだけではなく、
メソッドにもつけられるので、
修正でメソッドのみを作成したとかでも使えますね。
@return
返り値の説明です。
型だけだったらデフォルトで表示されるのですが、
その値がどんな値なのかの説明があると、なお分かりやすいです。
サンプルコード
package com.example.demo;
public class HelloWorld {
/**
* @return "HelloWorld"を返す。
*/
public String SetHelloWorld(){
String helloWorld = "";
helloWorld += "Hello";
helloWorld += " ";
helloWorld += "World!!";
return helloWorld;
}
}表示例
これがつけてあるか無いかで、
メソッドの中まで見に行く手間が省けます。
コードなんで結局、
結果が知れればいいわけですから。
書かれてない場合は、
F3でメソッドの中まで潜って、
コードを読むという手間が出てきます。
非常に効率が悪くなります。
ITを扱っているんですから、
効率にはこだわっていきましょう。
@throws
どの例外が発生する場合があるかの説明です。
なおかつ、どういった場合に発生するのかも記載できます。
サンプルコード
package com.example.demo;
public class NumberFormatExceptionSample {
/**
* @param scoreStr
* @return 引数の文字列方の数値をintに変換し、２倍にして返す
* @throws NumberFormatException 文字列が数値でない場合に発生
*/
public int GetDoubleScore(String scoreStr) throws NumberFormatException{
try {
Integer score = Integer.parseInt(scoreStr);
return score.intValue() * 2;
} catch (NumberFormatException e) {
System.err.println(e.getMessage());
e.printStackTrace();
throw e;
}
}
}
表示例
引数でString型の数値を受け取って、
それをintに変換し、尚且つ２倍にして返すコードの例です。
こういった型の変換では、よくエラーが起きます。
そのため、@throwsをつけて例外を明示しておけば、
コードの修正をする際に、ハンドリングがしやすいですし、
解析する際にも、どのメソッドで例外が投げられているのかが
分かりやすいです。
コードは、バグやエラーが発生した際に、
素早く、どこで起こったかがわかるように
書くべきです。
そうしておくことで、
無駄な残業は減るでしょう。
@throwsはその少しの助けとなります。
@see
関連項目を追加です。
これは、メソッドや外部リンクなどを
追加することが可能です。
サンプルコード
package com.example.demo;
public class SeeSample {
/**
* @param scoreStr
* @return 引数の文字列方の数値をintに変換し、２倍にして返す
* @throws NumberFormatException 文字列が数値でない場合に発生
* @see #RoundingNumber(float)
*/
public int GetDoubleScore(String scoreStr) throws NumberFormatException{
try {
Integer score = Integer.parseInt(scoreStr);
return score.intValue() * 2;
} catch (NumberFormatException e) {
System.err.println(e.getMessage());
e.printStackTrace();
throw e;
}
}
/**
* @param number 小数付きの数値
* @return 四捨五入された数
*/
public String RoundingNumber(float number) {
int roundNumber = Math.round(number);
return Integer.valueOf(roundNumber).toString();
}
}表示例
このように、メソッドを関連させたい場合は、
頭文字に「#」をつけると関連されられます。
外部リンクを関連づけさせたい場合は、
HTMLのように、
<a href=”外部リンク”></a>
とaタグを用いると関連付けさせられます。
外部リンクなら、クリックすれば、
そのサイトに飛べますし、
メソッドなら、そのメソッドの説明が見れます。
@seeタグのメソッドをクリックしたときの表示例
素晴らしい。。。
@link
文章中に、参考サイトや関連メソッド、変数などを埋め込むことが
できます。
メソッドAとメソッドBがあったとして、
メソッドAは、メソッドBを使用した後に使用する、や、
メソッド内で、特定のローカル変数を使用している場合に、
そのローカル変数を明示したい、
などの際に便利です。
サンプルコード
package com.example.demo;
public class LinkSample {
/** 2 */
private int i = 2;
/**
* @param scoreStr 文字列型の数値
* @return 引数の文字列方の数値をintに変換し、{@link #i}倍にして返す
* @throws NumberFormatException 文字列が数値でない場合に発生
* @see #RoundingNumber(float)
*/
public int GetDoubleScore(String scoreStr) throws NumberFormatException{
try {
Integer score = Integer.parseInt(scoreStr);
return score.intValue() * i;
} catch (NumberFormatException e) {
System.err.println(e.getMessage());
e.printStackTrace();
throw e;
}
}
/**
* @param number 小数付きの数値
* @return 四捨五入された数
*/
public String RoundingNumber(float number) {
int roundNumber = Math.round(number);
return Integer.valueOf(roundNumber).toString();
}
}表示例
このように文章中に、リンクとしてメソッドやローカル変数を埋め込めます。
ちなみに、これをクリックすると、
このように、メソッドや変数の説明を見ることができます。
もし、文章中にメソッドや変数を用いる場合は、
たった{@link }で囲うだけなので、
使用すると、よりコードが見やすくなるでしょう。
@code
これに関しては、
説明するよりも、
@codeを用いて書いた場合と、
用いずに書いて場合の違いを見せた方が
わかりやすいと思います。
以下、@codeを用いた例と
用いなかった例をご覧ください。
@codeを用いたサンプル
サンプルコード
package com.example.demo;
import java.util.ArrayList;
import java.util.List;
public class CodeSample {
/**
* @return {@code List<String>}型でHello World!!!を詰めるメソッド
*
*/
public List<String> GetHelloWorldList() {
var helloWorldList = new ArrayList<String>();
helloWorldList.add("Hello ");
helloWorldList.add("World");
helloWorldList.add("!!!");
return helloWorldList;
}
/**
* @param helloWorldList 繋げるとHello World!!!となるStringの{@code List<String>}
* @return Hello World!!!
*/
public String RoundingNumber(List<String> helloWorldList) {
String helloWorld = "";
for (String helloWorldStr : helloWorldList) {
helloWorld += helloWorldStr;
}
return helloWorld;
}
}表示例
@codeを用いないサンプル
サンプルコード
package com.example.demo;
import java.util.ArrayList;
import java.util.List;
public class CodeSample {
/**
* @return List<String>型でHello World!!!を詰めるメソッド
*
*/
public List<String> GetHelloWorldList() {
var helloWorldList = new ArrayList<String>();
helloWorldList.add("Hello ");
helloWorldList.add("World");
helloWorldList.add("!!!");
return helloWorldList;
}
/**
* @param helloWorldList 繋げるとHello World!!!となるStringのList<String>
* @return Hello World!!!
*/
public String RoundingNumber(List<String> helloWorldList) {
String helloWorld = "";
for (String helloWorldStr : helloWorldList) {
helloWorld += helloWorldStr;
}
return helloWorld;
}
}表示例
このように、@codeを用いるのと用いないのとでは、
「<」や「>」などの、
いわゆるエスケープ文字を用いないと表示されない文字が
表示できるかどうかの違いが出てきます。
サンプルコードのように、
Listの型を描きたい場合やMapの型を書きたい場合などに
よく用いられます。
あとがき
今回は、よく使うjavadocタグを紹介していきました。
javadocタグは、他にも様々あります。
使いこなせれば使いこなせるほど、
メソッドの説明がより分かりやすくなったり、
綺麗に整形できたりして、
他者から読まれやすく、修正のしやすいコードへと
近づきます。
