Javadocで使用する@throwsの数

Question

javadocやAPIにはどれくらい寛大に@throwsを使用する必要がありますか？例えば、私が持っている場合：

LDAPException 
NullPointerException 
IllegalArgumentException 
Exception 

私は一つ一つのために@throwsを使用する必要があり、または私はちょうど@throws Exceptionを言うべき？

Answer 1

理想的には、javadoc @throws節は、実際のメソッドthrows節のスーパーセットである必要があります。

たとえば、あなたの方法throws IOException場合、あなただけでなく、それが起こるかもしれない理由について話をする状況で、一般的なI/Oエラーが発生しますが、また@throws FileNotFoundException（IOExceptionのサブクラス）を説明するため@throws IOExceptionを有することができます。

同様に、throws NullPointerExceptionを宣言しなくても、これが発生する可能性がある場合は、チェックされていない例外であり、メソッドシグネチャに書き込まれる必要はありません。

あなたは@throws Exceptionになりますか？いいえ、しかし、より一般的には、あなたはthrows Exceptionではありません。それは別の議論です。しかし結果として、いいえ、この種の悪い習慣をjavadocで繰り返すのは良いことではありません。何が起こる可能性があるか？とにかく@throwsと一緒に1つずつ文書化してみませんか？

Answer 2

あなたが投げるすべての例外を文書化する必要があると思いますが、これはまたCheckStyleによって実施されるルールです。 Exceptionを文書化すると、すべての例外の非常に一般的なスーパークラスであるため、APIのユーザーに分かりやすい情報が提供されません。

このように、あなたのAPIのユーザーにとって意味のある例外を投げるべきだと思っています。層の技術に基づく例外ではありません。

たとえば、LDAPから別のものに切り替えることができますが、例外はもう一致しません。代わりに、インターフェイスを変更せずに実装を自由に変更することが重要です。

Javaプラットフォーム内で意味をなさない例外が見つからない場合は、ServiceExceptionなどの独自の例外を定義して例外翻訳を行うことができます。つまり、実装依存の例外をキャッチして例外を投げることができます。

NullPointerExceptionはランタイム例外（未チェック）です。一般に宣言されておらず、スローされず、また文書化されていません。これは、API内の初期化されていないか、またはnullパラメータによって生成される可能性があります。その場合、IllegalArgumentExceptionでそれを翻訳するのが理にかなっており、それを文書化します。

IllegalArgumentExceptionも実行時例外です。チェックしないと明示的に投げる必要はありませんが、スローしてドキュメントをスローするのは良い方法です。