This article is part of a longer running series on Error Handling with Exceptions.

Determining where to catch an exception can be one of the most difficult aspects to overcome in becoming comfortable with exceptions. These rules provide clear guidance and simplify the process by removing ambiguity.

Please note that this article’s scope is limited to the location of catch clauses. Questions on the state of the application and its ability to continue in the presence of specific exceptions will be addressed in future articles. The distinction between where to catch and what to do when an exception is caught is important, as this represents one of the most misunderstood facets of effectively working with exceptions.

Where to Catch

1. Catch specific exceptions locally if it is possible to mitigate the error and continue
2. Catch all exceptions locally if the error is benign within the context of a function’s intended purpose
3. Catch all exceptions at the function level when wrapping exceptions
4. Catch all exceptions at logical boundaries

Catch specific exceptions locally if it is possible to mitigate the error and continue

Although relatively uncommon, it is possible to automate the correction of an error condition and continue execution. For instance, a function that opens a file may be in a position to prompt the user and wait if an exception associated with a file in use is encountered. In these limited scenarios, it is appropriate to catch specific exception(s), correct the problem, and continue.

void MyFunction(void)
{
    while(true)
    {
        try 
        {
            AFileHandle     hFile;

            hFile = OpenFile(...);

            // Process file...
            
            break;
        }
        catch(FileInUseException const &ex)
        {
            PromptUser();
        }
    }

    // Continue...
}

Catch all exceptions locally if the error is benign within the context of a function’s intended purpose

There are times when an exception encountered within a function is benign within the context of the function itself. For example, failure to write to a log file may be critical when used for auditing purposes as part of a financial transaction but benign within the context of a function that is initiating emergency shutdown of a nuclear reactor.

It is important to reiterate that at this point in the discussion, it isn’t important to discuss what exception was thrown but rather where it was thrown and what that failure means within the larger context of the function.

Any time a function is called within a function that we are writing, we should ask ourselves “what does a failure here mean to the calling function”. In most cases, failure in a called function indicates failure for the calling function – we should not catch and let the exception percolate. However, if executing the calling function is far greater in importance than successfully completing the called function, we should catch and let the calling function continue.

// Note that this code is not production-quality and is
// intended for illustrative purposes only.

// Logging is critical to the function's success
void DoBankTransaction(void)
{
    Log::Write("Begin transaction");

    // Do transaction

    Log::Write("End transaction");
}

// Logging is not critical to the function's success
void BeginEmergencyShutdown(void)
{
    try { Log::Write("Begin emergency shutdown"); }
    catch(...) { /* Log exception */ }

    // Do shutdown

    try { Log::Write("End emergency shutdown"); }
    catch(...) { /* Log exception */ }
}

Catch all exceptions at the function level when wrapping exceptions

Exceptions should be caught and converted when implementing a function whose contract specifies that only exceptions of a specific type will be thrown. There are times when it can be convenient to specify that all exceptions that originate from a specific layer within an architectural hierarchy be of a consistent type (note that this convention becomes significantly less important when leveraging techniques to be outlined in “Generic Customization of Exception Messages”). In these cases, all exceptions should be caught and converted within the function itself. Care should be taken to ensure that the new exception thrown contains a reference to the original exception, as this is required when investigating the root cause of the problem while post-mortem debugging.

// Note that all exceptions eminating from this function
// will be of type MyFunctionException.
void MyFunction(void)
{
    try 
    {
        // Do something that may throw
    }
    catch(PotentialBaseException const &ex)
    {
        THROW_EXCEPTION(MyFunctionException(ex));
    }
    catch(std::exception const &ex)
    {
        THROW_EXCEPTION(MyFunctionException(ex));
    }
    catch(...)
    {
        THROW_EXCEPTION(MyFunctionException());
    }

    // This code is painful to write and maintain and is not
    // recommended. See the article "Error Handling with Exceptions:
    // Generic Customization of Exception Messages" for an
    // alternative.
}

Catch all exceptions at logical boundaries

All exceptions should be caught at logical boundaries, where a logical boundary may be an application’s entry point, subsystem boundary within a partitioned architecture (eg the boundary between a COM component and C++ layer), binary boundary, programming language boundary, or a “home screen” within a GUI application.

This article is part of a longer running series on Error Handling with Exceptions.

It can be a challenge to know when to throw exceptions and, unfortunately, the common guidance to throw in exceptional circumstances doesn’t do much to clarify the confusion. In this article, I will put forward postulates of when to throw exceptions and then explain each of those in more detail.

Note: In this article I will use the term function and method interchangeably. With regards to discussions of exceptions, precision associated with the differences between the two terms is not germane to the discussion.

When to Throw Exceptions

1. Exceptions should be thrown when the intended purpose of a function cannot be completed
2. When performance characteristics associated with exceptions for a particular function are prohibitive to the function’s use, a second, opt-in “nothrow” function should be created
3. “nothrow” functions cannot be created if there is more than 1 potential cause of failure within the function
4. The vast majority of mutable member functions should not return a value
5. All immutable member functions should return a value

Exceptions should be thrown when the intended purpose of a function cannot be completed

A function should do one thing, and that “one thing” should be captured in the return value (or an object state change if writing a mutable member function). A function’s failure to accomplish its intended purpose implies that a return value cannot be created and should result in an exception. We run into trouble when we attempt to:

Overload a return value with special meaning

// rval < 0 on failure
int ReturnPositiveNumber();

In this example, the return value represents a domain that is intentionally larger than the domain of a valid return value. While this does work, our selection of a return value is artificial, is not able to express valid constraints, and may restrict the domain of valid values (for example, what if std::numeric_limits::max() + 1 is a valid return value?). Furthermore, validation logic must be implemented by the caller. In the example above, validation is fairly intuitive – the function succeeded if the return value is greater than 0. However, what is the validation logic in this code below?

// Is nullptr valid?
MyObject * GetObject(); 

Again, the validation for this function may be fairly intuitive. However, any ambiguity introduced into code imparts some amount of burden on to the caller, and this burden is likely to lead to bugs when multiple developers are working within a code base.

Eschewing Return Values by Returning Error Codes Some systems require that functions return error codes, where values within the return type’s domain are well known. For example, COM requires that methods return HRESULTs to indicate success or failure. This solution does do a great deal to eliminate ambiguity associated with overloaded return values, but users pay a high price as a result.

HRESULT DoSomethingWithCOM(IUnknown *pUnknown);

When consuming the code above, HRESULTs contain rules that differentiate between values that indicate success and values that indicate failure. However, rigid solutions such as this prevent the return of actual results, meaning that the caller must create temporary variables to store pass as arguments when calling the function (note that it is possible to return successful values that can be overloaded to indicate a function’s result (S_FALSE), but such practices are generally discouraged).

Most troublesome, solutions such as this tend to be viral – it can be very difficult to communicate error codes to callers without returning the error code itself. This can result in a full call stack with knowledge of HRESULTs but no direct dependency on COM whatsoever. Leaky abstractions such as this immediately decrease the likelyhood of maintaining a layered architecture.

When performance characteristics associated with exceptions for a particular function are prohibitive to the function’s use, a second, opt-in “nothrow” function should be created

Sometimes, it makes sense to look before you leap. For example, it probably doesn’t make sense to throw exceptions in the following contrived code example:

for(int iCtr = 0; iCtr < 100000000; ++iCtr)
{
    int  iValue(Parse("This is not an int"));

    // ...
}

It may be advantageous to create a function similar to the first that does not throw an exception when invalid input is encountered. Fortunately, the new function does not violate the first postulate as its new name will reflect the intended return value’s purpose.

int Parse(char const *pszString);
bool TryParse(char const *pszString, int &value);

While helpful, this technique should be used with care, and these guidelines should be followed:

• Psychologically, the function that requires less discipline on the part of the caller (in this case, Parse) should be the more discoverable of the two variations. A user should knowingly opt-in to use a function that requires additional actions on their part (while this is actually accomplished with the name of the function itself, is can be valuable to make the more advanced function require slightly more effort to type). Note that leading a user towards the first function might have a negative impact on performance, but it is better to be correct that it is to be performant.

• The default function should always be implemented in terms of the advanced function (DRY: Don’t Repeat Yourself) as in the code below.

int Parse(char const *pszString)
{
    int value(0);

    if(TryParse(pszString, value) == false)
        throw std::invalid_argument("pszString");

    return(value);
}

bool TryParse(char const *pszString, int &value)
{
    // Parse, return false if invalid
}

“nothrow” functions cannot be created if there is more than 1 potential cause of failure within the function

It is not valid to create a “nothrow” option of a function if there are multiple points of potential failure within a function. It is important for debug-ability to know what error happened, not simply that an error happened. For example, the following function is not valid as there may be multiple reasons why the file could not be opened (file does not exist, file in use, permissions, etc).

bool TryOpenFile(char const *pszFilename, 
                 HandleToFile &file); // BAD!

Again, it is better to be correct than it is to be performant.

The vast majority of mutable member functions should not return a value

By definition, a mutable member function is intended to modify its internal state (generally through the modification of member variables). As such, the purpose of the function is to modify the state of the associated instance and not to return a value consumed by an external entity. While not always true, a mutable member function that returns a value should be subjected to various Code Smell investigations to see if such usage is appropriate.

All immutable member functions should return a value

By definition, an immutable member function should always return a value, as the function should not be modifying its internal state as a result of the function’s execution. Therefore, anything that is done by the function should be captured within the return value.

This article is part of a longer running series on Error Handling with Exceptions.

Right around 2000, I began to explore error handling via exceptions. There were many things I liked about exceptions; as a designer, I could:

• Ensure that users processed error conditions
• Provide rich contextual information along with the error itself

Unfortunately, I wasn’t at all comfortable with the introduction of jump/goto-like semantics when exceptions were introduced. In my naive-ate, I decided that I was going to create a solution that leveraged the best of both words.

I made good progress as I attempted to create an error code-based alternative to exceptions. Despite this progress I quickly realized that I was fighting a losing battle. The code that I was producing, while correct, was cumbersome to use – if I was having a hard time using it how could I expect success while evangelizing its use. Complexity resulted from the requirements that return codes must be composable and be convertible to a function’s result type. Worse, I realized that the end result of this effort was precluding the use of something that I had previously grown to love – the Standard Template Library. Finally, the killer was that the C++ new operator throws std::bad_alloc instead of returning null upon failure. By moving forward, I was swimming against the current of the entire C++ community and ultimately destined for failure.

It became overwhelmingly clear that it wasn’t possible, practical, or even prudent to try to fight the use of exceptions any longer. With this in mind, my focus changed to the evaluation and understanding of exceptions. This led to ultimately embracing exceptions as a superior means of error communication and propagation. I can honestly say that this change in perspective has had a profoundly positive impact on the designs that I produce and the quality of the code that I write. After literally hundreds of hours of thought, investigation, and experimentation, I hope to share some of what I learned along that journey.

In the coming days/weeks, I hope to write on the following topics. Please feel free to post in the comments if there is anything that you would like to see in these blog entries or specific questions that you may have on the topic.

Fully understanding and embracing exceptions is hard work, but my experience shows that the rewards greatly outweigh the cost.