プログラムのコードを書くのは一つのステップですが、そのコードが他者に理解され、効果的に使用されるためには、適切な説明が不可欠です。
JavaプログラムにはJavadocというコードを文書化するためのツールがあります。
本記事では、Javadocの重要性や利点、使用方法について記載していきます。
Javadoc（ジャバドック）とは？
Javadocは、Javaプログラムのコードにコメントを追加するツールです。
メソッド、クラス、およびフィールドにコメントを追加することで、そのコードの目的や機能を明確に説明します。
これにより、他の開発者がコードを理解しやすくなり、プロジェクトで一緒に作業するのも楽になります。
また、Javadocコマンドを使用することで、追加したコメントからAPI文書を自動的に生成し、使用方法を提供することができます。
※今回はJavadocコマンドの説明は含みません。
公式：JavaDoc Guide（JavaSE/21）
docs.oracle.com
Javadocの基本
Javadocの基本は以下の通りです。
- /** ～ */ の間に説明を記載
- クラス、定数、メソッドがコメントを記載する対象
- パラメータや返却値、作成者などの情報を@(アノテーション)を使用し、表現することができる
- コメントのフォーマットでHTMLタグを使用する
- その他にも便利なJavadocタグが存在する
下記がJavadocを記載したソースの例です。
/** * Javadocのサンプルクラス * @author 作成者 * @version 1.0 */ public class JavadocSample { /** 半角スペース */ private String SPACE_HALF = " "; /** * 社員IDと社員名から、社員IDと苗字を結合したものを返却<br> * 社員名がnullの場合は空文字を返却 * * @param empId 社員ID * @param empNm 社員名（半角スペースで結合された苗字と名前） * @return 社員IDと苗字を結合した文字列、または空文字 */ public String joinEmpIdWithEmpLastName(int empId, String empNm) { if(empNm == null) { return ""; } String[] empNmArray = empNm.split(SPACE_HALF); return empId + (empNmArray.length > 0 ? empNmArray[0] : ""); } }
Javadocの重要性
Javadocはチーム開発を行う上で非常に強力なツールです。
クラスやメソッドの使用方法が記載されたJavadocの有無で、開発や保守のスピードが大幅に変わります。
具体的には以下の例で説明します。
// Javadocあり
/**
* 契約書の条件と指定された住所コードから、条件に合う社員の一覧を返却
* <ul>
* <li>・契約Noから契約テーブルを検索し、該当の契約データを取得</li>
* <li>・契約データに記載している条件で、入力済みのものを抽出</li>
* <li>・都道府県コードと契約データの検索条件を基に、該当の社員一覧を取得返却する</li>
* </ul>
*
* @param contractNum 契約番号
* @param addressCd 住所コード
* @return マッチング対象の一覧
*/
public List<MEmployee> selectMatchingEmployeeList(String contractNum, String addressCd) {
// 契約情報を取得
// 契約情報から条件を抽出
// 社員情報を返却
}
// Javadocなし
public List<MEmployee> selectMatchingEmployeeList(String contractNum, String addressCd) {
// 契約情報を取得
// 契約情報から条件を抽出
// 社員情報を返却
}
Javadocがある場合、引数に対する返却値が一目でわかります。
Javadocがない場合、引数が理解しにくい場合があり、呼び出し元も含めてソースコードを順に見ていかなければなりません。
さらに、このメソッドが別の処理を呼び出し、その処理がさらに別の処理を呼び出すと、一つのメソッドを理解するのが難しくなります。
上記の例を見るだけで、Javadocの記載が開発や保守にとっていかに重要かが理解できると思います。
Javadocの記載方法
Javadocには記載のルールがあります。
記載する際に気を付けなければいけないのは、他の開発者が見て理解できるように書くということです。
ここからは実際に開発の現場でよく見かけるJavadocの例をご紹介したいと思います。
クラスの説明:
/** * Javadocのサンプルクラス<br> * Javadocの理解を深め、成長につなげる * * @author 作成者 * @version 1.0 */ public class JavadocSample { }
まずクラスのJavadocでは初めにクラスの目的を記載します。
クラスの役割や目的を簡潔に書くのがポイントです。
* Javadocのサンプルクラス<br> * Javadocの理解を深め、成長につなげる
次に作成者やバージョンを記載します。
作成者やバージョンは、プロジェクトによっては記載しない場合もあります。
* @author 作成者 * @version 1.0
メソッドの説明:
/** * メソッドの概要<br> * どんな処理をするのか記載 * * @param num どんな値 * @param str どんな値 * @return 何を返却するのか */ public String javadocSample(int num, String str) { return num + str; }
まずクラスのJavadocではクラスの目的を記載します。
クラスの役割や目的を簡潔に書くのがポイントです。
* Javadocのサンプルクラス<br> * Javadocの理解を深め、成長につなげる
次に製作者、バージョンを記載します。
この部分は記載が無いする現場も存在します。
* @author 作成者 * @version 1.0
定数の説明:
/** * ほげほげ */ private String HOGE_HOGE = ""; /** ほげほげ */ private String HOGE_HOGE = "";
定数名については上記の通り、値の説明を記載します。
HTMLタグ:
Javadocで記載したコメントが長くなり、見づらくなることはありませんか？
/** * この処理はJavadocの説明用のメソッドです。 * どうしても処理を書きたいので記載しています * 1.処理は特に記載していない * 2.処理が存在するメソッドをイメージしてもらいたい */ public void javadocSample() { }
このようなコメントが書かれている場合、Eclipse（IDE）などでは次のように表示されます。
この表示ではどこで区切りがあるのか、どの部分が実際の処理を表しているのかが一目でわかりません。
このような場合、Javadoc内でHTMLタグを使用してフォーマットを行うことができます。
/** * この処理はJavadocの説明用のメソッドです。<br> * どうしても処理を書きたいので記載しています * <ol> * <li>処理は特に記載していない</li> * <li>処理が存在するメソッドをイメージしてもらいたい</li> * </ol> */ public void javadocSample() { }
フォーマット後の表示は以下の通りです。
このようにすることで処理の内容がわかりやすくなります。
JavadocではHTMLタグを使用してフォーマットを行うことができ、その中でもよく使用されるものには次のものがあります。
- <br>タグ・・・改行
- <p>タグ・・・段落を付けたい
- <ul><ol><li>タグ・・・箇条書き、番号付きリスト
- <b><strong>タグ・・・強調
その他に<a>タグなどもありますが、あまり使用されることはありません。
<html>や<head>などは使用するとJavadocの構造が壊れる可能性があるので注意が必要です。
Javadocタグ:
HTMLタグとは別に、Javadoc内で使用できるタグも存在します。
よく使用されるタグとその内容は以下の通りです。
- @paramタグ：引数の説明
@param 引数 引数の説明
メソッドの引数に関する説明を記述します。
引数の順番通りにすべての引数について説明します。
引数が何を表しているかを説明する際、単に英単語を翻訳するのではなく、その意味を説明します。
- @returnタグ：返却値の説明
@return 返却値
返却される値に関する説明を記述します。
たとえば、booleanの場合は「true: チェック成功、false: チェックエラー」といった書き方をすることで、返却値の状態も伝わります。
詳細でわかりやすい説明が大切です。
- @throwsタグ：例外の説明
@throws Exception Exceptionの説明
メソッドがthrowする例外をすべて記述します。 例外にラッパークラスを指定している場合、例外の説明まで記述するかはプロジェクトによって異なります。
その他にも、@author（開発者、作成者）、@version（バージョン）、@see（関連事項として参照の追加）、{@link}（インラインのリンクを作成）、{@inheritDoc}（@Overrideなどで継承している場合、継承クラスのJavadocを参照）などが利用できます。
一覧（JavaSE/21）
docs.oracle.com
まとめ
長文となりましたが、私が最低限気を付けているポイントは以下の通りです。
- 説明はわかりやすく、わかりやすい形で表現する
- クラス、メソッド、定数に対するコメントは必須である
- @param、@return、@throwsの情報は漏れなく記載する
フォーマットであれば<br>だけでも十分であり、自分が知らないタグを調べてまで無理に使う必要はないと思います。
綺麗に見せたい、かっこよく書きたいとか考えるかもしれませんが、何よりも優先すべきは他の人が理解できるか？というポイントでそれが満たせればJavadocとして正しい記載だと思います。
