Should methods that throw RuntimeException indicate it in method signature?

For example, many methods in frameworks/JDK might throw

java.lang.SecurityException 

but this is not indicated in the method signature (since that is a practice normally reserved for checked exceptions). I want to argue that declaring RuntimeExceptions in method sigs has many benefits (akin to static type checking for example). Am I drunk or otherwise?

Solution 1:

I would not declare an unchecked exception in the signature, since it is misleading to the user of that API. It is no longer obvious whether the exception has to be explicitly handled.

Declaring it in the javadoc is a better approach since it allows someone to handle it if they think it is necessary, but knowing they can ignore it if they want. This makes the separation between checked and unchecked clear.

Solution 2:

From the Oracle Java tutorial:

"If it's so good to document a method's API, including the exceptions it can throw, why not specify runtime exceptions too?" Runtime exceptions represent problems that are the result of a programming problem, and as such, the API client code cannot reasonably be expected to recover from them or to handle them in any way. Such problems include arithmetic exceptions, such as dividing by zero; pointer exceptions, such as trying to access an object through a null reference; and indexing exceptions, such as attempting to access an array element through an index that is too large or too small.

Runtime exceptions can occur anywhere in a program, and in a typical one they can be very numerous. Having to add runtime exceptions in every method declaration would reduce a program's clarity.

Solution 3:

Take a look at the javadoc for Collection#add

There's a whole slew of unchecked exceptions mentioned:

Throws:
UnsupportedOperationException - add is not supported by this collection.
ClassCastException - class of the specified element prevents it from being added to this collection.
NullPointerException - if the specified element is null and this collection does not support null elements.
IllegalArgumentException - some aspect of this element prevents it from being added to this collection.

If you have the patience, I'd recommend thoroughly documenting the possible exceptions thrown by your methods this way. In a way, it's even more important to do this for unchecked exceptions, as checked exceptions are somewhat self-documenting (the compiler forces the calling code to acknowledge them).