41

I'm aware checked exceptions have to be handled or specified, but unchecked exceptions are optional.

If for some reason I can reasonably expect an unchecked exception to occur in a method, should I add it to the throws specification? Or should I keep the specification as short as possible?

mafu
  • 31,798
  • 42
  • 154
  • 247
  • 1
    I say add it. Source code is the best documentation. – Sotirios Delimanolis Jan 01 '14 at 18:25
  • 1
    @SotiriosDelimanolis The best documentation is the line which throws the exception and not a declarative statement that it may do so. – Marko Topolnik Jan 01 '14 at 18:48
  • 1
    @MarkoTopolnik I agree, but someone using the class might not have access to that source. They will, however, have access to the method signature. – Sotirios Delimanolis Jan 01 '14 at 18:50
  • 2
    @SotiriosDelimanolis In that case they will not have access to "the best documentation", will they? :) – Marko Topolnik Jan 01 '14 at 18:53
  • 2
    But @MarkoTopolnik, the declaration in the API is as close to the source as possible, and also visible directly in the IDE. I would not refute it like this. Maybe I'd even go further and say that the best place is actually the declaration and not the implementation, since the latter can change more easily while the declaration is (supposedly) compatible. Not sure if I'm interpreting too much into your statement :) – mafu Jan 01 '14 at 19:15
  • @mafu My comment was only on Sotirios's reference to the principle that "source code is the best documentation", which makes a distinction between *code comments* and *actual code*: it is only the actual code which cannot lie. An exception declaration is a close analogue of a code comment because it *talks about code* instead of *being code*. As for which exceptions should be declared, it is usually redundant to declare such general exceptions as `NullPointerExecption` or `IllegalArgumentException` because there is little point in ever catching them. – Marko Topolnik Jan 01 '14 at 19:19
  • @MarkoTopolnik Thanks for the explanation. Subjective details aside, it sounds like we basically all agree here. – mafu Jan 02 '14 at 13:15

4 Answers4

32

If for some reason I can reasonably expect an unchecked exception to occur in a method, should I add it to the throws specification?

Since unchecked exceptions indicate programming errors, declaring them in the throws clause should be avoided. Generally, catching these exceptions should not be attempted, except for the highest level of your program. There are a few exceptions (pun intended) to this rule - for example, in production code you should be catching NumberFormatException.

Note: Sometimes, authors of frameworks make their base exception inherit RuntimeException (e.g. HibernateException). Exceptions like that should be caught as well.

Sergey Kalinichenko
  • 714,442
  • 84
  • 1,110
  • 1,523
  • 2
    Except for the `NumberFormatException`. One should always catch this when the number is entered by the user. – Sibbo Jan 01 '14 at 18:28
  • 3
    Good point. On the other hand, if the exceptions just happens to be unchecked even though the user could handle it, then I could add it, according to this reasoning. Is that right? – mafu Jan 01 '14 at 18:28
  • 4
    Josh Bloch agrees with this answer in _Effective Java_: "do not use the throws keyword to include unchecked exceptions in the method declaration" (2e, p. 252). His rationale would encourage declaration of `HibernateException` in the throws clause, though. – David Aug 18 '15 at 21:31
  • 1
    Checkout RestTemplate from springframework, the methods declare in the signature RestClientException which is a RuntimeException. – johnlemon Aug 05 '16 at 07:25
  • 1
    This is a basic fundamental of exception handling that most of the people are missing. – Sorter Oct 15 '18 at 06:47
9

That is a design decision. Normally you wouldn't do that. But if you think it is crucial for the user of your code to catch an Exception, then it is a way to hint him doing that. Another way would be to just add it to the documentation, and explain why it is important to catch the Exception.

sync
  • 5,350
  • 2
  • 23
  • 32
Sibbo
  • 3,796
  • 2
  • 23
  • 41
7

explicitly declaring in throws-clause is not necessary since it is about runtime exceptions, but you should document it in javadoc so users can see under which circumstances this exception might occur and what does it mean.

Meno Hochschild
  • 42,708
  • 7
  • 104
  • 126
0

There is no use or impact thats why we should not declare unchecked exceptions in the throws keyword as throws keyword required only to convince compiler and unchecked exceptions are not checked by compiler as these are runtime exceptions.

Chanchal Agrawal
  • 1
  • 1