Exceptions are a block of code’s way of saying “something, possibly unexpected, happened and as a result I can’t do what I’m supposed to do.” They have been around long enough that we’ve taken them for granted. We’ve lost touch with the importance of having a good exception handling strategy. At least, that’s the conclusion I’ve reached from much of the code I’ve read over the last several years. So I want to spend some time writing about what I’ve learned when it comes to handling exceptions.
Exception Types
There are basically two types of exceptions. Checked exceptions are checked at compile-time. This means that a method throwing a checked exception needs to declare that it does so, and code calling that method must provide a handler for that exception. An exception handler typically comes in the form of a try…catch block that is provided in many programming languages.
An unchecked exception occurs at execution time and is also referred to as a runtime exception. These exceptions do not need to be declared in a method as being thrown (since a programmer will not likely know in advance whether such an exception will be thrown), and exception handlers are not required for them.
Each of these exception types has a type of use case for which it is suited. Checked exceptions represent cases in which the calling code is expected to be able to handle and resolve the exception. These are usually expected problems that can occur during normal system operation and are often documented as exception flows in a use case. For example, consider a scenario in an ATM app in which the user tries to withdraw more money than is present in a checking account.
Expected problems that occur during normal system operation are represented as checked exceptions.
Unchecked exceptions represent cases in which the calling code is not expected to be able to handle or resolve the exception. These are unforeseen scenarios that typically aren’t documented in a use case. For example, consider a scenario in which an app is not able to reach a backend server. There is usually nothing that the calling code can do to resolve the problem.
Unforeseen or unexpected problems that aren’t expected to be resolvable are represented as unchecked exceptions.
Exception Handling
Here are some elements of a good exception handling strategy that I’ve learned over the years:
Do not swallow exceptions
An exception is “swallowed” if its exception handler does nothing to resolve or report the problem. At the very least, log the exception. Also, consider whether the caught exception should be wrapped in an custom application-specific exception and rethrown. If there is nothing the code can do to handle an exception, don’t catch it.
Preserve stack traces when logging exceptions
Most logging libraries allow you to pass the exception object in addition to the message to be logged. For example:
catch (Exception e) {
var message = "Error occurred while updating the employee record";
logger.error(message, e);
throw new ApplicationSpecificException(message, e);
}Take advantage of that. This usually results in the stack trace showing up in the log, which helps developers figure out the source of the problem.
Don’t throw an instance of an exception base class
Throwing an instance of an exception base class, such as Exception or RuntimeException in Java or Exception or SystemException in C#, provides no helpful information regarding the problem that has occurred beyond (hopefully) a good message. As a corollary, declaring that your method throws an exception base class is tantamount to saying “sh*t can happen in this method but I’m not going to tell you what it is.” It’s lazy coding; don’t do it.
Wrap caught exceptions in custom exceptions
Most of the exceptions your code catches will be thrown by the runtime environment or by other libraries or frameworks your code uses. These exceptions are usually fairly generic. Wrap these exceptions in custom exceptions that provide more insight into the problem that has occurred. This is how to avoid throwing instances of a base exception class. For example, if a user is asked to enter a numeric account number and mistakenly includes a letter, you may get a NumberFormatException. This exception describes what happened at a root level but doesn’t include any context that may help someone reading the code in the exception handler understand what’s happening. Wrapping that exception in a custom exception, say MalformedAccountNumberException, provides some context to make the code easier to understand. Here’s an example of how to do that:
try {
...
}
catch (NumberFormatException e) {
var message = String.format("Invalid account number %s", accountNumber);
logger.error(message, e);
throw new MalformedAccountNumberException(message, e);
}Since the original exception is contained in the wrapping exception, there is a trace from the application-specific exception down to the original low-level exception that is the root cause. Also, if these custom exceptions are checked, you can declare that your method throws them instead of base exceptions.
Reduce the number of checked exceptions your method will throw
In most languages, you have to declare the checked exceptions that your methods will throw. If the list of declared exceptions is long, you need to think about what’s really happening and see if you can make the list shorter. When calling some lower-level code, you may find that the code can throw several different types of exceptions. For example, if you’re using the Java Thread API, you may have a block of code that could throw SecurityException, IllegalThreadStateException and InterruptedException. These aren’t base exception classes but you don’t want to just copy them into the throws list of your method. Firstly, it gives the impression that lots can go wrong in your code and secondly, you don’t want the users of your code to have to deal with that many exception types. If you follow the practice of wrapping lower-level exceptions in custom exceptions, chances are that the long list of lower-level exceptions your code has to catch will map to a much shorter list of custom exceptions. For example, at a higher level of abstraction, the three exception types mentioned above may map to one custom exception.
Avoid catching base exceptions, except as a last resort
Be careful when catching base exceptions. An exception handler allows you to respond to an exception. Different exception types usually require different responses. If you only provide a handler for a base exception, you will have to handle all subtypes of that base exception the same way. Even if all you’re going to do is log the exception, wrap it in a custom exception and rethrow it, take the time to think about whether you would want to log different exception types differently and wrap them in different custom exceptions in order to provide more insight into the context in which a problem occurred.
A base exception handler can be useful as a catch-all, for example, to catch a checked exception you didn’t anticipate. If you catch exceptions with this handler, make sure you log it so you can see which exceptions are being caught. If it tends to be the same exceptions repeatedly, you can add handlers for those exceptions.
Soften checked exceptions that can’t be handled
You may encounter a situation in which you have to catch a checked exception that the code calling your method can’t be expected to handle. For example, Java’s JDBC library that provides the ability to issue SQL queries will throw a checked exception called SQLException. Most of the time you get it, there’s a problem with the database connection, a malformed SQL query, etc. The calling code won’t be able to recover from these problems. In this case, soften the checked exception by wrapping it in a custom unchecked exception. For the SQLException, you can create a custom unchecked exception whose name indicates what’s being done with the database, say EmployeeRecordUpdateException. Wrapping the SQLException within the custom exception provides context for the error and a trace back to the root cause.
Throw early, catch late
This well-known principle of exception handling states that you should throw an exception as soon as you can, at the point when the problem occurs, and wait until there is enough information and context to handle the exception properly. Typically, this means that an exception is thrown in lower-level code and propagates up the call stack until it reaches a method that is at the appropriate level of abstraction for resolving the problem.
Log exceptions at every relevant level
Logging and exception handling go hand-in-hand. Always log an exception at the point where the problem occurs; this will document the root cause. At one or more levels higher in the call stack, there may be points at which useful contextual information is available. At each of these points, catch the exception, log it, wrap it in a custom exception appropriate for the level of abstraction, and throw the custom exception.
If all you need to do with an exception is clean up, use finally instead of catch
Sometimes you may not be able to handle an exception but your code needs to do some cleaning up if the exception occurs. In that case, use a try…finally construct, in other words, omit the catch block.
Don’t throw an exception from a finally block
If you have code doing some cleaning up in a finally block and that code throws an exception, make sure that you completely handle any exceptions that occur there. Any exceptions coming out of finally block will have no context. For example, consider the following code:
try {
doSomething();
}
finally {
cleanUp();
}If doSomething() throws an exception and cleanUp() also throws an exception, you won’t have access to the first exception because it will not be in the scope of your finally block. You can log the exception in both blocks, but the original exception object will not be available in the finally block, so you won’t have traceability from the clean-up code to the exception from which the code is cleaning up. Thus, in your application log, you’ll see the log messages coming from the finally block but with no contextual information.
Exception handlers are not flow-control constructs
Don’t use exception handlers for flow control. A common example is validating user input. Suppose a method receives a numeric identifier in a string. You’ve probably seen code like this:
Customer customer;
try {
customer = findCustomerByIdentifier(identifier);
}
catch (NumberFormatException e) {
customer = findCustomerByName(identifier);
}Catching and responding to an exception is often less efficient in this kind of situation than checking the condition in a more straightforward way. Rather than using the exception handler for flow-control, a better way to write the above code is:
Customer customer;
var identifierIsNumeric = identifier.matches("[0-9]+");
if (identifierIsNumeric) {
customer = findCustomerByIdentifier(identifier);
}
else {
customer = findCustomerByName(identifier);
}This approach also more clearly describes what the correct format for a customer identifier is.
Conclusion
Having a good exception handling strategy and using it consistently can significantly reduce the cognitive effort demand required to understand your code. Be sure to include good logging practices into your exception handling strategy. Effective logging together with sound exception handling gives you good insight into what’s happening in your code when errors occur.