Javaコメントの書式｜単複コメントとJavadoc書式と使い方と解説
Javaコメントの書式｜単複コメントとJavadoc書式と使い方と解説
Javaの単行複数行コメントの書き方、Javadocの書式と使い方、全てのタグを解説。Javadocタグの使用例をサンプルコードで分かりやすく解説した。
Javaコメント Javadoc 目次
Javaのコメント
Javaのコメントは、//（単行）、/* */（複数行）の2つの書き方がある。この他に /** */ とすることで Javadoc 用のコメントを記述できる。
//は//から改行までをコメントとして認識する。単行コメント 記述例 // 単行コメントを書く/* */は/*をコメント開始タグ、*/をコメント終了タグとして認識し、タグの内側をコメントとして認識する。複数行コメント 記述例 /* 複数行コメントを書く */ /* 複数行コメントを書く */ /* * 複数行コメントを書く */
他言語のコメント書式は コメントの言語別書式機能比較 を参照。
Javadocのコメント
/** */ は Javadoc（ジャバドック） と呼ばれ、メソッドの引数や戻り値の意味を記述するために使う。
これを書くことで、HTML形式のAPIドキュメントを生成したり、開発ツール（EclipseやVSCodeなど）上でマウスを置いた時に説明文がポップアップ表示されるようになる。
基本コマンド
コマンドプロンプトやターミナルで、ソースファイルがあるディレクトリに移動して実行する。
-d doc：生成されたHTML群を doc というディレクトリに出力する指定（ディレクトリ名は自由に変更可能）。
[ソースファイル名.java]：対象となるJavaファイルを指定する。*.java とすればカレントディレクトリ内の全ファイルを対象にできる。
javadoc -d doc [ソースファイル名.java]オプション
パッケージ単位で出力指定する。
-sourcepath でソースのルート（srcなど）を指定し、-subpackages で対象のパッケージ名を指定する。
javadoc -d doc -sourcepath src -subpackages com.exampleエンコーディングの指定（文字化け対策）
ソースが UTF-8 で書かれている場合、これを指定しないと文字化けすることがある。
javadoc -d doc -encoding UTF-8 -charset UTF-8 [ファイル名]Javadoc のタグ
- ブロックタグ：独立した行に記述して特定の情報ブロックを作るタグ。
（@param@return@throws@exception@see@deprecated@author@version@since@serial@serialData）。
【主要なブロックタグ】
@param：メソッドの引数の説明を記述するタグ。
@return：メソッドの戻り値の説明を記述するタグ。
@throws / @exception：メソッドが投げる可能性のある例外の説明を記述するタグ。
@see：関連するクラスやメソッドへのリンクを生成するタグ。
@since：機能を導入したバージョン、または機能を導入したJDKのバージョンを記述するタグ。
@deprecated：非推奨であることを記述するタグ。
@author：クラスやインターフェースの作成者を記述するタグ。
@version：ソフトウェアのバージョンを記述するタグ。
@param
メソッドの引数の説明を記述するタグ。
書式：@param 変数名 変数の説明
@param タグ記述例
@param userid ユーザーID
@param password パスワード
public boolean loginCheck(String userid, String password) {
}
@return
メソッドの戻り値の説明を記述するタグ。
書式：@return 戻り値の説明
@return タグ記述例
@return 認証成功は true、認証失敗は false
public boolean loginCheck(String userid, String password) {
if ( 処理 ) {
return true;
} else {
return false;
}
}
@throws
メソッドが投げる可能性のある例外の説明を記述するタグ。
書式：@throws Exceptionクラス名 例外の説明
@throws タグ記述例
@throws Exception 認証エラーまたはシステム例外時にスロー。
public boolean loginCheck(String userid, String password) throws Exception {
}
@exception
メソッドが投げる可能性のある例外の説明を記述するタグ（@throws と同じ意味。開発現場では特別な理由がない場合は、一般的に@throwsを使用する）。
書式：@exception Exceptionクラス名 例外の説明
@exception タグ記述例
@exception IllegalArgumentException 引数が null の不届き者は throws IllegalArgumentException する。
if (userid == null || password == null) {
throw new IllegalArgumentException("ユーザーIDとパスワードは必須です。");
}
@see
関連するクラスやメソッドへのリンクを生成するタグ。公式リファレンスなどの外部サイトのURLを直接記述することもできる。
書式：@see パッケージ名.クラス名#メソッド名またはメンバー名（# は対象のクラスのメソッドまたはメンバーを示す）
@see タグ記述例
クラスの指定方法：クラス名 で指定する。
@see UserData同一クラス内メソッド名の指定方法：#メソッド名（引数の型, ...） で指定する。
@see #validationCheck(UserData)別クラスのメソッドの指定方法：クラス名#メソッド名（引数の型, ...） で指定する。
@see LoginEvent#loginCheck(Connection, Statement, UserData)別パッケージのクラスのメソッドの指定方法：パッケージ名.クラス名#メソッド名（引数の型, ...） で指定する。
@see java.util.Collections#sort(java.util.List)@deprecated
非推奨であることを記述するタグ。@Deprecated（アノテーション）と対にして記述することで、ソースコードとドキュメントの両方で非推奨であることを明示でき、メンテナンスしやすい。
書式：@deprecated 説明
@deprecated タグ記述例
@deprecated loginメソッドは {@link #loginCheck(String, String)} メソッドに移行したので非推奨。
@Deprecated
public boolean login(String userid, String password) {
}
@author
クラスやインターフェースの作成者を記述するタグ。
書式：@author 作成者
@author タグ記述例
@author 株式会社ほげほげ ピ世ピ世@version
ソフトウェアのバージョンを記述するタグ。
書式：@version ソフトウェアのバージョン
@version タグ記述例
@version 1.00@since
機能を導入したバージョン、または機能を導入したJDKのバージョンを記述するタグ。
書式：@since 機能を導入したバージョンまたは機能を導入したJDKのバージョン
@since タグ記述例
@since JDK25.0.1他言語のコメント書式は コメントの言語別書式機能比較（Javadoc、PHPDoc、Docstring、Go Doc、RDoc など） を参照。
{@index}
以下のコードは、実際のソースコードでのJavadocのコメントの事例である。
import java.util.HashMap;
import java.util.Map;
/**
* <pre>
* ユーザー認証を管理するクラス。
* ログインチェックに使用する。
*
* ＜ビジネスクラス共通説明＞
* データベースアクセスに関する全ての処理を実装できる。
* エラー処理：例外処理が発生した場合は、上位層へthrows Exceptionする。
* 呼出元クラスによるエラー時の自動ロールバックを実行する。
*
* ＜このクラス固有の説明＞
* 引数で受け取ったユーザーIDをキーに、ユーザー管理テーブルからユーザー情報を取得する。
* ユーザー情報が存在した場合、パスワードが一致するかチェックし、一致した場合、{@link UserData}クラスにユーザー情報を設定する。
* ユーザー情報が存在しなかった場合、エラーを返す。
* ログインに3回失敗した場合、始末書を提出するまで二度とシステムを利用できないよう利用制限する。
* </pre>
*
* @see LoginEvent#loginCheck(Connection, Statement, UserData)
* @see #validationCheck(UserData)
* @see UserData
* @version 1.00
* @since JDK25.0.1
* @author ピ世ピ世
*/
public class LoginAuthBusiness {
/** ユーザーごとの失敗回数を記録するマップ */
private Map<String, Integer> mapFailureCounts = new HashMap<>();
/** 利用制限がかかる閾値 */
private static final int MAX_ATTEMPTS = 3;
/**
* 指定されたユーザーID、パスワードでログイン認証を試行する。
* 例外処理が発生した場合は、上位層へthrows Exceptionする。
*
* @param userid ユーザーID
* @param password パスワード
* @return 認証成功は true、認証失敗は false
* @throws IllegalArgumentException 引数が null の不届き者は throws IllegalArgumentException する。
* @throws LoginSuspendedException 3回失敗して「断罪（利用停止）」された場合にスロー。解除には始末書の提出が必要。
* @throws Exception 認証エラーまたはシステム例外時にスロー。
*/
public boolean loginCheck(String userid, String password) throws LoginSuspendedException, Exception {
// 引数チェック
if (userid == null || password == null) {
throw new IllegalArgumentException("ユーザーIDとパスワードは必須です。");
}
/*
既に制限されているかチェック
ログインに3回失敗した場合、始末書を提出するまで二度とシステムを利用できないよう利用制限する。
*/
/** Javadocコメントの間違った使用例：これはローカル変数なのでJavaDoc対象外（普通のコメント扱い） */
int currentFailures = mapFailureCounts.getOrDefault(userid, 0);
if (currentFailures >= MAX_ATTEMPTS) {
throw new LoginSuspendedException("【利用制限中】貴殿は既に3回失敗し、断罪されました。始末書を提出してください。");
}
// 認証処理（シミュレーション）
if ("admin".equals(userid) && "pass123".equals(password)) {
mapFailureCounts.remove(userid);
return true;
} else {
currentFailures++;
mapFailureCounts.put(userid, currentFailures);
if (currentFailures >= MAX_ATTEMPTS) {
throw new LoginSuspendedException("失敗回数が " + MAX_ATTEMPTS + " 回に達しました。断罪（利用停止）を実行します。");
}
throw new Exception("ログイン失敗。残り試行回数: " + (MAX_ATTEMPTS - currentFailures));
}
}
}
おすすめ記事
 | 10日で使えるPHP | 未経験のサルでも分かるPHPの学習サイト 文系未経験、サルでも10日でPHPを使えるように内容を構成した独学向け学習サイト。不要な基礎はバッサリ切り捨て必要な基礎を十分に深堀した・・・ 続きを見る |