Javadocの@throwsタグを記載しなくてはいけない時

Javadocの@throwsタグを記載しなくてはいけないのはどんな時なのかが分からず、公式サイトを見ても知識不足で意味が分からなかったので、ざっくり嚙み砕いてメモしておく。

公式サイトより

 Throws Tag

 The purpose of the @throws tag is to indicate which exceptions the programmer must catch (for checked exceptions) or might want to catch (for unchecked exceptions).

Guidelines - Which Exceptions to Document

Document the following exceptions with the @throws tag:

・All checked exceptions.
　(These must be declared in the throws clause.)
・Those unchecked exceptions that the caller might reasonably want to catch.
　(It is considered poor programming practice to include unchecked exceptions in the throws clause.)
　Documenting these in the @throws tag is up to the judgment of the API designer, as described below.

公式サイトをGoogle翻訳

スロータグ

タグの目的@throwsは、プログラマーがキャッチする必要がある例外 (チェック済み例外の場合)、またはキャッチしたい可能性がある例外 (チェックされていない例外の場合) を示すことです。

ガイドライン - 文書化すべき例外

次の例外を@throwsタグで文書化します。

・すべてのチェック済み例外。
　(これらは throws 句で宣言する必要があります。)
・呼び出し元が当然キャッチしたい未チェックの例外です。
　(未チェックの例外を throws 句に含めることは、プログラミングの習慣として適切ではありません。)
これらを@throwsタグに文書化するかどうかは、以下に説明するように、API 設計者の判断に委ねられます

前提知識として

• 検査例外(Checked Exception)
• 非検査例外(Unchecked Exception)

が何なのかを知っておく必要があります。
こちらの記事(検査例外(Checked Exception)、非検査例外(Unchecked Exception)とは？)に検査例外(Checked Exception)、非検査例外(Unchecked Exception)について記載しましたので、分からない方はそちらをご覧ください。m(_ _)m

Javadocで@throwsタグで文書化するパターン

検査例外(Checked Exception)の場合

• 検査例外(Checked Exception)ならば問答無用で@throwsタグを書きましょう！！

公式サイトより

・All checked exceptions.
　(These must be declared in the throws clause.)

公式サイトをGoogle翻訳

・すべてのチェック済み例外。
　(これらは throws 句で宣言する必要があります。)

　(これらは throws 句で宣言する必要があります。)

意訳：検査例外は、throws節でメソッドの宣言に記述する必要があります。

検査例外(Checked Exception)とは何ぞや？という方はこちらをご覧ください。

throws節って何だっけ？という方はこちら

• throws節をメソッドの宣言に記述することで、メソッド内で例外が発生した場合に自身のメソッド内で補足(catch)するのではなく、呼び出し元の関数に例外を投げる

throws構文

    アクセス修飾子 戻り値 メソッド名(引数) theows 例外クラス1, 例外クラス2{
        // 例外処理を含む処理
    } 

例

    public String readFile() throws IOException {
        // ファイルの読み込み処理
    }

• throws節をメソッドの宣言に記述することで、その処理で例外が発生することが分かる
• throws節で例外が記述されているメソッドは、呼び出し元の関数側で、その例外に対して何らかの処理をする事がjavaの仕様で決まっている
  (例外を処理するコードを記述しないとコンパイルエラーになる)

非検査例外だけど、呼び出し元のメソッドにExceptionを投げている場合

• 非検査例外はtry-catch文も、throws節も書く必要が無い
  →非検査例外は、呼び出し元のメソッドにわざわざExceptionを投げる必要が無い(というより、投げないのが一般的)
  しかし、仮にもし非検査例外を呼び出し元のメソッドに投げている(= 呼び出し元のメソッドでキャッチしなければいけない)のであれば、@throwsを書きましょう！！

公式サイトより

・Those unchecked exceptions that the caller might reasonably want to catch.
　(It is considered poor programming practice to include unchecked exceptions in the throws clause.)
　Documenting these in the @throws tag is up to the judgment of the API designer, as described below.

公式サイトをGoogle翻訳

・呼び出し元が当然キャッチしたい未チェックの例外です。
　(未チェックの例外を throws 句に含めることは、プログラミングの習慣として適切ではありません。)
これらを@throwsタグに文書化するかどうかは、以下に説明するように、API 設計者の判断に委ねられます

　(未チェックの例外を throws 句に含めることは、プログラミングの習慣として適切ではありません。)

意訳：非検査例外を呼び出し元のメソッドに投げるのは、プログラミングの習慣として適切ではない。

非検査例外(Unchecked Exception)とは何ぞや？という方はこちらをご覧ください。