Rules for Working with Exceptions

Monday, August 04, 2008

Since I work on the consulting side of Oracle I tend to see a lot of code from clients and it surprises me how often I still see developers making basic mistakes when working with exceptions, both when throwing them and when consuming them. At the risk of beating a dead horse, since this topic has been covered to death, here are some basic rules I try to live by when working with exceptions.

Rule #1. If you catch an exception and wrap it in a new thrown exception, make sure to chain the exception by including it in the constructor of the newly thrown exception. For example:

try {
blah..blah..blah
} catch (IOException e) {
   throw new MyApplicationRuntimeException(e);
}

Rule #2. Include meaningful information in the exception, specifically include whatever information is necessary in order to track down the issue if someone needs to look into it further. Nobody likes dealing with exceptions that have something stupid like "Unexpected error" set as the message. As a positive example, if you're writing code for a financial application and an account creation operation fails, include the account number along with other relevant information in the exception that would enable support or operations staff to diagnose the issue. This additional information can be wrapped in fields of a custom exception class or simply included in the exception message.

Rule #3. Log exceptions where they are handled not where they are thrown. I'm sure we have all seen examples of applications where the developers log the same exception over and over again as it traverses up the stack. Applications should only log an exception once and the easiest and most practical way to enforce this is to only log the exception where it is handled. In other words, if your code simply catches the exception and rethrows it as a wrapped exception then do not log it, rely on the code above you to log the exception properly.

Rule #4. In general, prefer unchecked exceptions except in cases where there is a reasonable chance the receiver of the exception can do something meaningful in response, in these cases use checked exceptions. There has been a lot of debate over the usage of checked vesus unchecked exceptions over the years, I tend to fall somewhat in the middle of the debate in that I feel both types are useful. When throwing an exception, the key to knowing which type to throw is to ask youself "Can someone do something useful in response to this exception?". If the answer is yes, then use a checked exception. If the answer is no or you are in doubt then use an unchecked exception. In general the vast majority of thrown exceptions in an application should be unchecked.

Ruke #5. Always document the use of unchecked exceptions in javadoc through the use of the @throws clause.

Posted by Gerald Nunn at 7:29 PM | Categories: Java | | | Permalink