WEB+DB PRESS Vol.51 特集2「“巧い”メソッド設計」連動企画

第1回 Javadocリファレンス

この記事を読むのに必要な時間:およそ 9 分

クラスソースファイル

クラスに対してのコメントを記述しますリスト3図5⁠。最初の文はパッケージページの概要テーブルにコピーされます。メソッドの最初の文はクラスページのメソッド概要テーブルにコピーされます。

リスト3 クラス/メソッドのドキュメントコメント

package webdb51;

import java.io.IOException;
import java.io.Serializable;
import java.util.List;

/**
 * クラスに対してのコメントを記述します。
 * ここでは以下の内容を記述します。
 * <UL>
 * <LI>クラスがどういうことをするのかの説明
 * <LI>インスタンスが取り得る状態についての情報。
 *     例) ファイルがオープンされている状態とクローズされた状態での振る舞い。
 * <LI>OSやハードウェアへの依存性。例)java.io.Fileクラス
 * <LI>クラスの不変条件や一般契約。例)java.lang.Comparableインタフェース
 * <LI>インスタンスのスレッド安全性レベル(注2)。
 *     例)java.lang.Appendableインタフェース
 * <LI>セキュリティ制約。例)java.lang.RuntimePermissionクラス
 * <LI>直列化の形式
 * <LI>インタフェースを実装する場合またはクラスを継承する場合の注意点。
 *     例)java.util.AbstractListクラス
 * <LI>他のクラスとの関連性。
 * <LI>外部仕様への参照。例)java.net.URLクラス
 * @see "Effective Java第2版"
 */
public class DocSample implements Serializable
{
    /**
     * フィールドの説明。
     * @serial 直列化されるフィールドの説明。
     * 以下の内容を記述します。
     * <UL>
     * <LI>フィールドが表しているもの
     * <LI>有効な値の範囲。例)java.awt.Font#style
     * <LI>nullを許可するか
     * </UL>
     */
    private String field1;

    /**
     * 定数が意味することを説明する。例)java.lang.Integer#MAX_VALUE
     */
    public static final int CONST1 = 0;

    /**
     * publicメソッドにはAPI利用者向けに以下の説明を記述します。
     * <UL>
     * <LI>メソッドの期待される振る舞い
     * <LI>状態がどのように遷移するか。
     * 例)close()メソッドによってオブジェクトがclose状態に遷移する。
     * <LI>メソッドの副作用の有無とその内容。副作用とは事後条件を達成するのに
     *     明らかに必要としない変化(注3)。
     *     例) バックグラウンドのスレッドを起動する。
     * <LI>メソッド呼び出しの事前条件,事後条件。例)Integer.parseInt(String)
     * <LI>スレッド安全性レベル
     * <LI>セキュリティ制約
     * <LI>使用するアルゴリズムの定義。例)java.lang.String#hashCode()メソッド
     *     (どのように実装しているかではありません。)
     * <LI>OSやハードウェアへの依存性。例)java.io.File#getCanonicalPathメソッド
     * </UL>
     * @param param1 パラメータの説明。有効な引数の範囲やnullを許容するかを記述します。
     * @param list パラメータに副作用がある場合はその内容を明記する。
     * @return 戻り値の説明。戻り値の値の範囲や型,nullの可能性を記述する。
     * @throws IOException 例外の説明。例外の発生原因を記述する。
     *         チェックされる例外はすべて書く。
     * @throws NullPointerException 実行時例外は必要なものだけ記述する。
     */
    public int function1(int param1, List list) throws IOException
    {
        list.add(param1);
        return list.size();
    }

    /**
     * protectedメソッドは継承利用者向けにメソッドの内容を説明します。
     * publicメソッドに記述する内容に加えて以下の内容を記述します。
     * <UL>
     * <LI>オーバーライドするときの注意点。
     *     例)javax.servlet.GenericServlet#init(ServletConfig)メソッド
     * <LI>守るべき不変条件や一般契約。
     *     例)java.lang.Object#equals(Object)メソッド
     * </UL>
     * @throws IOException チェックされる例外のコメントはサブクラスに自動的に継承されます。
     * @throws IllegalStateException 実行時例外のコメントは手動で継承しなければなりません。
     */
    protected void function2() throws IOException
    {
    }

    /**
     * package privateメソッド,privateメソッドは保守担当者向けに以下の内容を記述します。
     * <UL>
     * <LI>実装のアルゴリズム。外部には見せないので,どのように実装しているかまで記述してもよいです。
     * <LI>データ構造
     * <LI>なぜそのような実装にしたのか。採用するときに参考にした参考資料等を記述する。
     *     例)J2EEパターンのFrontControllerパターンを元に作成した。
     * <LI>未解決の問題点。開発期間や技術上の未解決の問題について記述する。
     *     例)JDK 1.5以降で開発する場合は,Class#getSimpleName()でクラス名を取得する。
     * <LI>改善ポイントや代替手段
     * </UL>
     */
    private void function3()
    {
    }
}

図5 クラスコメントの出力例

図5 クラスコメントの出力例

ここでメソッドコメントの具体例を2つ示しますリスト4リスト5⁠。前者はメソッドの宣言以上のことを説明していないため,無意味なコメントになっています。このようなコメントを書いていては誰もJavadocを読む気にはなれません。

リスト4 悪い例

/**
 * 指定された名前と電話番号で登録します。
 * @param name 名前
 * @param tel 電話番号
 * @return 現在の人数
 */
public int entry(String name, String tel)

リスト5 良い例

/**
 * 指定された名前と連絡先で湯河原合宿の参加者として登録します。
 * 定員を超えた場合はキャンセル待ちとして扱います。
 * @param name 合宿参加者の名前を示す文字列
 * @param tel 連絡先の電話番号を示すハイフン区切りの文字列。
 *            電話番号にはnullを指定できます。
 * @return 受付を完了した参加者数。キャンセル待ちは含みません。
 * @see #getWaitingList() キャンセル待ちリスト
 */
public int entry(String name, String tel)
注2)
『Effective Java第2版⁠⁠/Joshua Bloch著/柴田 芳樹 訳/ISBN978-4-89471-499-1/ピアソン・エデュケーション/2008年/269ページ
注3)
『Effective Java第2版⁠⁠/Joshua Bloch著/柴田 芳樹 訳/ISBN978-4-89471-499-1/ピアソン・エデュケーション/2008年/196ページ

そのほかのファイル

Javadocドキュメントに画像ファイルを含めたいことがあると思います。その場合は,パッケージディレクトリ配下にdoc-filesというディレクトリを作成して,そこに画像ファイルを含めます。Javadocツールはdoc-filesディレクトリの内容を出力先ディレクトリにコピーします。

著者プロフィール

小棚木章直(おだなぎあきなお)

(株)富士通ビー・エス・シーに勤務しているソフトウェアエンジニア。主にJava読書会で活動。アジャイル開発に興味があり,XPJUGのイベントに参加することも多い。最近はバグパターンをテーマにしている。