More Related Content
More from Appresso Engineering Team (20)
Effective Java 輪読会 第7章 項目43-44
- 2. 第7章 メソッド
項目38 パラメータの正当性を検査する
項目39 必要な場合には、防御的にコピーする
項目40 メソッドのシグニチャを注意深く設計する
項目41 オーバーロードを注意して使用する
項目42 可変長引数を注意して使用する
項目43 null ではなく、空配列か空コレクションを返す
項目44 すべての公開 API 要素に対してドキュメントコメントを書
く
2
- 4. 目当ての物がないときは何を返す？
4
店でチーズを買おうとしたら、チーズがない状況
チーズがないという特別な状況のため、余分な処理が必要となる
private final List<Cheese> cheesesInStock = ...;
/**
* @return 店にあるすべてのチーズを含む配列、もしくは、
* 買えるチーズがなければ null。
*/
public Cheese[] getCheeses() {
if (cheesesInStock.size() == 0) // なぜかチーズがない状況を特別扱いにする
return null;
...
}
Cheese[] cheeses = shop.getCheeses();
if (cheeses != null && // 戻り値を使う前に余分な null チェックが必要
Arrays.asList(cheeses).contains(Cheese.STILTON))
System.out.println("Jolly good, just the thing.");
- 5. なぜ null を返す？
5
主張：『配列を割り当てるコストを回避できるので、空配列よりも
好ましい』
反論１：そのメソッドがパフォーマンス上の本当の原因？プロファ
イリングでそう示された？でなければ、そのレベルで心配すること
ではない
それって、時期尚早の最適化かもしれない
項目55 「注意して最適化する」を参照
反論２：項目を一つも返さない呼び出しすべてが、同一の長さゼロ
の配列を返すことが可能。割り当てるコストはかからない
長さゼロ配列は不変
不変オブジェクトは制限なく共有しても問題ない
項目15 「可変性を最小限にする」を参照
- 6. コレクションから配列を返す方法
6
コレクションから指定した型の配列を書き出すための標準イデオム
// コレクションから配列を返す正しい方法
private final List<Cheese> cheesesInStock = ...;
private static final Cheese[] EMPTY_CHEESE_ARRAY = new Cheese[0];
/**
* @return 店にあるすべてのチーズを含む配列。
*/
public Cheese[] getCheeses() {
// Collections.toArray(T[])の仕様は、
// 入力配列がコレクションを保持するのに十分な大きさであれば、入力配列を返すことを保証する
// したがって、空配列を割り当てることはない
return cheesesInStock.toArray(EMPTY_CHEESE_ARRAY);
}
- 7. コレクションを返すメソッドの場合
7
同一の不変の空コレクションを返すことはできる
ちなみに
Collections.emptyList や emptySet、emptyMap があるが
Arrays.emptyArray はない（項目25参照）
// コレクションのコピーを返す正しい方法
public List<Cheese> getCheeses() {
if (cheesesInStock.isEmpty())
return Collections.emptyList();
return new ArrayList<>(cheesesInStock);
}
- 10. API のドキュメント
10
Javadoc
ドキュメンテーションコメント、またはドキュメントコメントと呼ばれ
たもの
ソースコードから自動的に API ドキュメント（HTML）を生成する
規約: “How to Write Doc Comments for the Javadoc Tool”
ドキュメントコメントの記述対象
すべての公開されている物※の宣言の前にドキュメントコメントを書く
保守可能なコードを書くためには、ほとんどの公開されていない物※に対
しても書くべき
ドキュメントコメントの保守コストを考慮すればコードの可読性を上げる方向
もある
※クラス、インタフェース、コンストラクタ、メソッド、フィールド
- 12. ドキュメントコメントの記述原則
12
メソッド
メソッドのクライアントとの間の契約を簡潔に記述すべき
何を行っているかを述べる。どのように処理を行っているかではない
ただし、継承のために設計されたクラスでのメソッドは例外（項目17）
@param タグ:すべてのパラメータに対して記述
@return タグ:戻り値があれば
@throws タグ:スローするすべての例外に対して記述 （項目62）
すべての事前条件と事後条件を列挙すべき
メソッドの副作用も文書化すべき
ジェネリックメソッドの型パラメータを文書化すべき
- 13. ドキュメントコメントの記述原則
13
コード例を記述する場合は Javadoc の {@code} タグが好ましい
{@code} タグ内の HTML メタ文字はそのまま使用できる
HTML の <code> や <tt> タグだと、メタ文字をエスケープする必要が
ある
単語 “this” の使用について
慣習的、呼び出されたインスタンスメソッドのオブジェクトのことを指
す
HTML メタ文字（<, >, &）の生成は {@literal} タグが良い
変換後のドキュメントだけ考えるなら “<” “>” “&” でも
いいが
ソースコードと生成結果の両方の読みやすさを意識すべき
- 14. 実務においてのドキュメントコメント
14
概要説明の記述慣例
メソッドやコンストラクタ:処理を説明する動詞句
クラス、インターフェイス、フィールド:表される事柄を説明する名詞句
パッケージレベルのドキュメントコメント
Java 1.5 以降は package-info.java に書くべき
パッケージ宣言とパッケージアノテーションを入れることできる（必須
ではない）
メソッドコメントは {@inheritDoc} タグで内容を一部継承できる
スーパークラスよりインターフェイスが優先される
継承することで文書を再利用可能（独自の制約があって、使いにくいけ
ど...）
必要があれば、外部文書へのリンクを含む
- 16. まとめ
16
すべての公開 API 要素に対してドキュメントコメントを記述
ドキュメントコメント内で標準規約に従った統一されたスタイルを
採用
ドキュメントコメント内の HTML メタ文字は取扱い要注意
