レベル: 初級 Scott W. Ambler (scott_ambler@ca.ibm.com), Practice Leader, Agile Development, Rational Methods Group, IBM
2000年 8月 17日 Java メンバー関数を文書化する際の記載内容として、以下の提案を参考にしてください。
すべての Java メンバー関数には、関数を理解する上で重要なすべての情報を表す、メンバー関数文書と呼ばれる一種のヘッダーが含まれる必要があります。この情報には、以下の事項が含まれるのが望ましいでしょう (ただし、これだけとは限りません)。
メンバー関数の動作の内容およびその理由
メンバー関数の動作を文書化することにより、第三者は、コードを再使用できるかどうかを 確認しやすくなります。この文書により、第三者は、コードをコンテキストに入れやすくなります。また、第三者が自分のコードに実際に新たな変更を加えるべきかどうかを決めやすく なります (新たな変更を加える理由と、元のコードが現在のように書かれた理由が相反している場合など)。
どのメンバー関数をパラメーターとして渡す必要があるか
また、メンバー関数に対するパラメーターがどのように使用されるかを指定する必要があります。この情報により、第三者はメンバー関数に何を渡すべきかが分かります。これには、javadoc@param タグが使用されます。
メンバー関数が何を戻すか
メンバー関数が何を戻すか (戻り値がある場合) を文書化することにより、他のプログラマーが戻り値またはオブジェクトを適切に使用することができるようになります。これには、javadoc@return タグが使用されます。
既知のバグ
メンバー関数に関する未解決の問題は文書化し、他の開発者がメンバー関数の弱点と問題を把握できるように する必要があります。特定のバグがクラスの複数のメンバー関数に発生する場合は、その関数だけではなくクラスに対して文書化する必要があります。
メンバー関数がもたらす要注意の例外
メンバー関数によって起きうるすべての例外を 文書化し、他のプログラマーがコードに手を加える場合に何が必要かを分かるようにする必要があります。これには、javadoc@exception または@throws タグが使用されます。
可視性の判断
メンバー関数の可視性に関する決定について、他の開発者から問い合わせがあることが予想される 場合 (おそらく、他のオブジェクトがメンバー関数を呼び出す前に メンバー関数を共用にしているはずです)、この決定内容を 文書化する必要があります。これにより、他の開発者に考えが伝わり、決定内容を 確認するために余計な時間を費やさずにすみます。
メンバー関数によるオブジェクトの変更方法
メンバー関数によってオブジェクトが変更される場合は、このことを 指示する必要があります。たとえば、銀行口座のwithdraw() メンバー関数によって 口座の残高が変更されるとします。この情報により、他の Java プログラマーは、メンバー関数の 呼び出しによってターゲット・オブジェクトがどのように影響されるかを正確に理解できるようになります。
必要に応じたメンバー関数の呼び出し方法の例
コードの一部の動作を確認する上で最も簡単な方法の 1 つは、例を参照する 方法です。よって、メンバー関数の呼び出し方法の例 を 1 つか 2 つ入れておくと、非常に役に立ちます。
適切な事前条件および事後条件
事前条件はメンバー関数が正常に実行されるための制約で、事後条件はメンバー関数の 実行終了後に真となる特性または表明 です (参考文献のObject-Oriented Software Construction を参照)。事前条件および事後条件は、メンバー関数の 使用方法の範囲を正確に規定しながら、メンバー関数が書かれる際に決定された前提事項をさまざまな方法で表します (参考文献のBuilding Object Applications that Work を参照)。
すべての並行処理 (concurrency) に関する問題
並行処理は、多くの開発者にとって新しく複雑な概念であり、これは 経験のある並行処理を取り扱うプログラマーが相手でも、古くて複雑な概念だといえます。したがって、Java プログラミング言語の並行処理プログラミング機能を 使用する場合、この機能を完全に文書化する必要があります。Doug Lea (参考文献のConcurrent Programming in Java を参照) は、クラスに 同期メンバー関数と非同期メンバー関数の両方が含まれる場合 (特に、他の開発者が メンバー関数を安全に使用できるためにメンバー関数に対する無制限のアクセスが 必要な場合)は、メンバー関数が依存する実行コンテキストを文書化する必要があると言っています。実行可能インターフェースをインプリメントする クラスの setter (フィールドを更新するメンバー関数) が 同期化されていない場合、その理由を文書化する必要があります。最後に、メンバー関数を変更または多重定義し、その同期方法を 変更する場合も、その理由を文書化しなければなりません。
文書化の例
図 1 は、Java メンバー関数のヘッダーの文書化例です。@return などの標準 javadoc タグや、@precondition などの 非標準タグがどのように使用されているかに注意してください。これらの新しい タグをサポートするために、これらを認識する doclet を開発するか、これらを認識するよう 調整できる Java 開発ツールを購入する必要があるでしょう。
図 1 メンバー関数のヘッダーの文書例
/**
Withdraw the funds from this account.
@param amount The amount of the withdrawal.
@return The amount withdrawn.
@precondition The account must have the funds available for them to be
withdrawn.
@postcondition If the funds are available they will be withdrawn and a record
of the withdrawal will be made.
@throws InsufficientFundsException An indication that the account balance and
overdraft limit were not sufficient to allow the withdrawal to occur.
@modifies Yes Debits the funds and posts a record into the account transaction
history.
@concurrency Changes to an account balance, such as a withdrawal, must occur
as an ACID transaction.
*/
|
重要なことは、何かを文書化するのは、それによってコードがより明確になる場合だけにすべきだということです。すべての要素をあらゆるメンバー関数に適用できる わけではないため、上記の要素をすべてのメンバー関数に対して文書化する必要はありません。しかしながら、作成する各メンバー関数ごとに、これらの一部を文書化することは必要でしょう。
参考文献
Java メンバー関数の文書化に関する詳細については、以下の資料を参照してください。
著者について
記事の評価
| 
