Error Reporting

When an error occurred, the program provided us with the following information:

1. The context in which the error happened (typically the primary action being executed)
2. What data was being worked on at the time of the error
3. What action actually detected the error
4. What requirement of that action failed to be met

With this information, we (the user) were able to correct a bad file and continue working.

If all actions that handle errors provide the aforementioned bits of information, the user stands a good chance of being able to correct the errors themselves. And when the user cannot fix the problem, there is enough information that a developer can narrow down the problem to one area of the code. Although this kind of error handling is very useful and the program will be all the more stable and robust because of it (and the user won't be made to feel like a dummy by bad error messages), this level of error handling does have a cost. Expect to spend anywhere between 50%-80% of your code just handling errors. Good error handling is not an afterthought, something to be slapped into place with a hope and a prayer. Good error handling, like a good algorithm, must be properly designed and tested. Good error handling is worth the investment because the payoff is more satisfied customers.

Now, if the program was just smarter about handling errors on its own so we don't have to do all the work, we'd be really happy users. For a program to be smart enough to recover from many errors, the program needs to be designed to deal with errors.

Design Away Errors

The first step in dealing with errors in a program is to design the program to not have errors. Okay, so that's perhaps reaching for the impossible. We can at least design the program to minimize the errors that can occur. For each error our design makes impossible, that's one less error we have to handle and the user has to see.

Way back in the beginning, I had an example of an action that added two numbers. Here is a summary:

If the program can handle it, we can eliminate one error if we change the requirements for success to be:

By making the result a 64-bit integer, we've eliminated the possibility of an overflow (no matter how you add two 32-bit values, the result will always fit in a 64-bit integer). However, now our program must handle 64-bit values. Plus, what happens if we want to add two 64-bit numbers? Change everything to use 128-bit integers? In this example, to avoid a never-ending escalation of bitness, we could make a choice, a compromise, that says our code will never add two 64-bit integers.

Let's look at the file reading example, where the file reader was looking for a “HEADER” section before a “DATA” section. If we design the actions to allow the sections to appear in any order, we can eliminate the error where the “HEADER” section must appear before the “DATA” section. The trade-off is the action needs to load in the entire file instead of reading the file one line at a time, looking for the desired sections. So the action will take up more memory.

A second alternative could be the action reads the file twice, once to find the “HEADER” section and a second time to find the “DATA” section. That might take a long time, if the file is stored across a network connection. So the action will take more time.

A third alternative is to have a default “HEADER” section, in case an actual “HEADER” section cannot be found. The trade-off here is whether the default section will work for most “DATA” sections. There is probably a very good reason the “HEADER” section is expected in the file, after all.

Don't expect to be able to design away all errors; the best you can do is eliminate the more obvious source of errors. Sometimes you have to go through the process of implementing the design to see a way to eliminate the possibility of an error. Design and implementation of a complex product such as software is an iterative process, where one step requires revisiting a previous step with new information. Also, every change made in the design usually means a trade-off was made somewhere else.

Summary of Error Handling Design

So now you know the fundamental art of designing error handling:

1. Identify the actions a program can take
2. Identify the requirements for each action
3. Determine which actions will handle errors so the program can be left in a usable state
4. Design those actions to detect the appropriate errors
5. Provide sufficient information about each error so the user has a good chance of correcting it themselves rather than calling support for help
6. Where possible, design away the possibility of at least some errors

Return Error Code

The first approach is the simplest. Define a list of error codes that your program knows about and then designate one of those error codes as indicating success. Every procedure that can detect an error is written to return one or more error codes for error conditions or return the success code if no error is found. Every call to a procedure tests the return value to see if an error has occurred and if so, either handle the error right there or pass the error on to a higher layer.

In pseudo-code, returning an error code looks something like this:

mainlevel() procedure:
  set done = false
  while done is false do
    errorcode = call sublevel() procedure
    if errorcode does not equal success then
      report error to user
    else
      continue processing
      if processing is done then
        set done = true
      end if
    end if
  end while
end mainlevel()

sublevel() procedure:
  if program state is wrong then
    return error code indicating bad program state
  else
    do something useful
    if something useful failed then
      return error code indicating the algorithm failed
    else
      return success code
    end if
  end if
end sublevel()
                    

Global Error Location

The C standard library used a global error code in its original design. Each function would return a value that was pertinent to what the function did, for example, fopen() returns a pointer to a FILE structure representing the file just opened. If fopen() failed, it returns a 0 or NULL pointer, indicating an error had occurred. Your program would then consult the global errno variable to find out what happened. Later versions of the C standard library, such as the one from Microsoft, moved away from using a global errno variable to returning error codes from each function. For example, fopen() changed to fopen_s(), and now returns an error code instead of a FILE pointer. Global error variables such as errno are not a good idea because of the problem of one procedure possibly overwriting the error code for a previous procedure before the first error was handled. It can be argued that the program was not properly structured to prevent overwritten error codes but a global variable makes it very easy to get into this kind of situation.

There is one place where the concept of a “global” error code can still find use and that is with classes. A software “class” represents data and methods (procedures) that are closely associated. The error code becomes just a property of the class and all of that class's methods use the class error code. There is much less chance of one procedure stomping on the error code of another.

The only difficulty with using any kind of “global” error location is figuring out what is an invalid value to return from a procedure. For memory pointers it's easy: return a 0 or null pointer, since such pointers are almost universally not allowed to be accessed. But an arithmetic operation that returns an integer where the value could be any one of the allowed integer values presents a problem. Do you reserve one value that is not likely to occur and treat that as the flag that an error occurred? Or do you tell the caller to check the global error location to see if it has been set to an error after the arithmetic operation has completed? The latter approach would look something like this:

set global_error = success
mainlevel() procedure:
  result = call do_add(1, 2) procedure
  if global_error does not equal success
    return to user that an error occurred in do_add()
  else
    report result to user
  end if
end mainlevel()

do_add(a, b) procedure:
  set global_error = success
  set result = 0
  if a is out of bounds or b is out of bounds then
    set global_error = code for out of bounds error
  else
    set result = a + b
  end if
  return result to caller
end do_add()
                    

Every procedure that can return an error must be sure to set the global error location to a success value as the first step. Every caller of a procedure must remember to check the global error location to see if an error occurred. That's two things that can be missed by a developer and if either one is missed, an error could be missed and the user will get bad results for no explained reason.

This is why global error locations are not used much anymore: it is too easy to miss one vital step and cause the program to no longer be trustworthy. Returning error codes is a little better; however, it is still up to the caller to check the return value and respond to errors accordingly. All too often, a programmer will ignore the return codes and thus an error can escape unnoticed until the user's data is corrupted. To be fair, error return codes may be the only way to handle errors in situations where more robust approaches such as exceptions are not supported. The only thing you can do then is be very diligent and consistent in checking return codes.

One tip for making error codes work a little easier is to mandate that all procedures either return nothing or they return an error code. If a procedure needs to return a non-error value, it should do so through some other mechanism than the return statement (for example, through a reference or pointer to a variable passed in as an argument).

Error Code as Message

An error code is a number and, by itself, a number is meaningless. So it is very useful to convert an error code into human-readable text. But how to translate an error code into the right kind of message for the user?

There are several ways to solve this problem, what I present here is just one solution. The assumption in this example is every error code is unique, although parts of the actual message might change depending on the exact failure mechanism (for example, an error code for File Not Found might have a message that says “Failed to find ‘simonsays.txt’ file.”).

The following is presented in pseudo-code form. There is the action that detects and reports the error, and two helper actions. One helper action is used to save the error message with the error code while the second helper action retrieves the error message given the error code.

readfile(filename) procedure:
    if filename does not exist then
        set message = "Failed to find {0}", where {0} is filename
        call set_error_message('File Not Found' code, message) procedure
        return 'File Not Found' code
    end if
    read the file
    return success code
end readfile()

set_error_message(error code, message) procedure:
    set global error list at index error code = message
end set_error_message()

get_error_message(error code) procedure:
   set message = value in global error list at index error code
   return message
end get_error_message()
                    

Here is an example of how the above would be called to get the error message:

mainlevel(filename) procedure:
    set return code = readfile(filename)
    if return code is success code then
        do something with file contents
    else
        set message = call get_error_message(return code) procedure
        report return code, message
    end if
end mainlevel()
                    

Exceptions have the advantage of storing the message in the exception object itself, thus eliminating the need for a “global” list that maps an error code to a string.

Exception Terminology

Trigger an exception. This action is commonly called raising or throwing an exception, depending on the mechanism used for exceptions in the computer language. Triggering an exception puts the exception in motion and is done after an error has been detected.

Catching an exception. The part of the program that catches the exception is typically known as an exception handler and is indicated by a code construct that says “all exceptions of a particular type stop here”. The code that catches the exception can then do something about the exception, from handling it to reporting it to the user to re-triggering the exception. Another term sometimes seen for an exception handler is a “catch block”, named after the language keyword used to mark an exception handler (the term “catch block” is specific to C++, C#, and Java since “catch” is the keyword those languages use to mark an exception handler).

Unwinding the stack. This action represents what occurs when an exception is triggered. The exception follows the call stack, undoing each procedure call as the exception looks for an exception handler. Note that some computer languages don't have stacks, but nonetheless have some way of following a sequence of calls that needs to be unwound. As the stack is unwound, each procedure is allowed to clean up after itself. This is why exceptions are so nice to use, as there is a (more or less) automatic way to handle the process of getting the program back into a good state.

What are Exceptions?

The fact that I'm providing definitions for terms associated with exceptions should be a clue that exceptions are much more complex than simple error codes. Exceptions were created to deal with error conditions in object-oriented programming where an object fails to be constructed. Very early on it became obvious that exceptions were good for a whole range of situations, not just object construction.

Exceptions are implemented in a computer language to minimize the damage done to a program in the face of an error, and are almost always associated with object-oriented languages. A computer language generally has to work very hard to process a thrown exception. For example, in the process of unwinding the stack to look for exception handlers, the language must make sure that all objects allocated in a procedure being unwound are properly de-allocated and cleaned up. Not to mention any local variables that might have been declared on the stack. The developer has to be involved in every step along the way to make sure the program is left in some kind of usable state as the stack is unwound. In fact, this is the heart of error handling using exceptions, also known as exception handling.

Exceptions affect the overall structure of the program in a more fundamental way than using error codes. Error codes follow the normal program flow and thus are easy to trace (call a procedure and if it fails, do something; otherwise do something else). Exceptions don't seem to follow normal program flow as an exception can jump from the middle of a procedure up many levels before being caught. You have to be aware of all the calls between the point where the exception was thrown and where it was caught and make sure each procedure leaves the program in a usable state in the face of an exception passing through — even if the exception is not explicitly handled in those intermediate procedures.

So what benefits do exceptions provide that makes all this complexity worthwhile? There are three primary benefits: 1) it concentrates error handling in selected locations, 2) the code is much easier to read, and 3) it is easy to provide custom error messages with each exception. Here is a fragment of code in C# that shows these benefits (e.Message provides the custom error message).

Whether you read C# or not, the overall flow should be understandable. At no time in the normal flow of the code (lines 5 through 9) are errors even considered. Instead, the try..catch block that surrounds the normal flow of code will catch any exceptions thrown as a result of an error. Also note the number of exception handlers (“catch blocks”), each dedicated to a specific exception. This allows the code to provide meaningful messages to the user.

As you may have noticed, there are more lines dedicated here to error handling than there are lines apparently doing anything useful. This is normal. There are two good reasons for this: 1) all of the error handling for the ShowDataFile() action is in one place and 2) the functions being called do not have to report errors to the user, only detect them (making those functions simpler).