【Effective Java】項目４４：すべての公開 API 要素に対してドキュメントコメントを書く

Javadoc

Javadoc はソースコードに書いたドキュメンテーションコメントを処理して、ソースコードから自動的に API ドキュメンテーションを生成することができます。 Javadoc のドキュメントコメント規約は Java の一部ではありませんが、事実上の API となっています。

規約は以下のページから閲覧することができます。

How to Write Doc Comments for the Javadoc Tool

ある API を使えるようにするためにはそれを文書化する必要があります。 API を適切に文書化するためには公開されているすべてのクラス、インタフェース、コンストラクタ、メソッド、フィールドにドキュメントコメントを書かなければなりません。

メソッドのドキュメントコメント

メソッドに関するドキュメントコメントではメソッドとクライアントの取り決めについて明確に記述する必要があります。 特にメソッドでは事前条件と事後条件について正しく記述するべきです。

事前条件とは API のクライアントがメソッドを呼び出すために成立していなければならない条件です。 事後条件は呼び出しが正常に終了した場合に成立する条件です。

一般的に、事前条件は @throws タグに暗黙的に記述されます。 事前条件違反の場合には例外が発生するのが一般的だからです。

これに加えて、メソッドのドキュメントコメントでは副作用とスレッド安全性についても記述するべきです。

ドキュメントコメントの例

ドキュメントコメントにはクラスやメソッドを構成する要素を完全に記述するべきです。

• すべてのパラメータに対する @param タグ
• メソッドに戻り値がある場合の @return タグ
• チェックされる・されないに限らない例外の @throws タグ

慣例として、@param と @return のタグに続くテキストは名詞句です。 @throws タグに続くテキストは if から始まる例外がスローされる条件を記述した文、もしくは算術式です。

/**
  * Returns the element at the specified position in this list.
  *
  * <p>This methods is <i>not</i> guaranteed to run in constant
  * time. In some implementations it may run in time proportional
  * to the element position.</p>
  *
  * @param index index of the element to return
  * @return the element at the specified position in this list
  * @throws IndexOutOfBoundsException if the index is out of range
  *         ({@code index < 0 || index >= size()})
  */
E get(int index);

日本語では以下のようになります。

/**
  * リスト内の指定された位置にある要素を返します。
  *
  * <p>このメソッドは定数時間で処理を終えることを<i>保証しません</i>。
  * いくつかの実装では要素の位置に依存した時間がかかるかもしれません。</p>
  *
  * @param index 返される要素のインデックス
  * @return リスト内の指定された位置にある要素
  * @throws IndexOutOfBoundsException インデックスが範囲外の場合
  *          ({@code index < 0 || index >= size()})
  *
  */

ドキュメントコメント内は HTML タグが利用できます。 Javadoc ユーティリティはドキュメントコメントを HTML に変換し、 コメント内の任意の HTML 要素はそのまま HTML タグとなります。

ジェネリックス、enum、アノテーションのドキュメントコメント

ジェネリクス型やジェネリクスメソッドでは、必ずすべての型パラメータのドキュメントコメントを書くべきです。

/**
 * An object that maps keys to values. A map cannot contain
 * duplicate keys; each key can map to at most one value.
 * ...
 *
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 */
public interface Map<K, V> {
  ...
}

enum 型のドキュメントコメントには、public メソッドだけでなくすべての定数にもドキュメントコメントを付けてください。

/**
 * An instrument section of a symphony orchestra.
 */
public enum OrchestraSection {
    /** Woodwinds, such as flute, clarinet, and oboe. */
    WOODWIND,
    /** Brass instruments, such as french horn and trumpet. */
    BRASS,
    /** Percussion instruments, such as timpani and cymbals. */
    PERCUSSION,
    /** Stringed instruments, such as violin and cello. */
   STRING;
} 

アノテーションのドキュメントコメントには、すべてのメンバーにコメントをつけてください。

/**
 * Indicates that the annotated method is a test method that
 * must throw the designated exception to succeed.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    /**
     * the exception that the annotated test method must throw
     * in order to pass. (The test is permitted to throw any 
     * subtype of the type described by this class object.)
     */
    Class<? extends Throwable> value();
}

感想

本文には細かい Javadoc のタグの説明が書いてあったけど省いた。

次は第８章。少し終りが見えてきた気がする、、、と思ったけど普通にまだまだだった。