Parent issue: #19807
Coverage table
Chapter link
Content
Image
Text
Documenting Unchecked Exceptions
It is generally desirable to document the unchecked exceptions that a method can throw: this allows (but does not require) the caller to handle these exceptions. For example, it allows the caller to "translate" an implementation-dependent unchecked exception to some other exception that is more appropriate to the caller's exported abstraction.
Since there is no way to guarantee that a call has documented all of the unchecked exceptions that it may throw, the programmer must not depend on the presumption that a method cannot throw any unchecked exceptions other than those that it is documented to throw. In other words, you should always assume that a method can throw unchecked exceptions that are undocumented.
Note that it is always inappropriate to document that a method throws an unchecked exception that is tied to the current implementation of that method. In other words, document exceptions that are independent of the underlying implementation. For example, a method that takes an index and uses an array internally should not be documented to throw an ArrayIndexOutOfBoundsException, as another implementation could use a data structure other than an array internally. It is, however, generally appropriate to document that such a method throws an IndexOutOfBoundsException.
Keep in mind that if you do not document an unchecked exception, other implementations are free to not throw that exception. Documenting exceptions properly is an important part of write-once, run-anywhere.
Guidelines
This chapter doesn't appear to contain any implementable rule. Proposal:
| Documentation Comments Rule |
Checkstyle Checks Used |
Sample files |
| Documenting Unchecked Exceptions |
-- |
|
Parent issue: #19807
Coverage table
Chapter link
Content
Image
Text
Documenting Unchecked Exceptions
It is generally desirable to document the unchecked exceptions that a method can throw: this allows (but does not require) the caller to handle these exceptions. For example, it allows the caller to "translate" an implementation-dependent unchecked exception to some other exception that is more appropriate to the caller's exported abstraction.
Since there is no way to guarantee that a call has documented all of the unchecked exceptions that it may throw, the programmer must not depend on the presumption that a method cannot throw any unchecked exceptions other than those that it is documented to throw. In other words, you should always assume that a method can throw unchecked exceptions that are undocumented.
Note that it is always inappropriate to document that a method throws an unchecked exception that is tied to the current implementation of that method. In other words, document exceptions that are independent of the underlying implementation. For example, a method that takes an index and uses an array internally should not be documented to throw an ArrayIndexOutOfBoundsException, as another implementation could use a data structure other than an array internally. It is, however, generally appropriate to document that such a method throws an IndexOutOfBoundsException.
Keep in mind that if you do not document an unchecked exception, other implementations are free to not throw that exception. Documenting exceptions properly is an important part of write-once, run-anywhere.
Guidelines
This chapter doesn't appear to contain any implementable rule. Proposal: