Title: Professionalism in Programming #23

The stupid user manhandled your lovely program. Perhaps they provided the wrong input, or attempted an operation that's patently absurd. A good program will point out the mistake, and help the user rectify it. It won't insult them, or whinge in an incomprehensible manner.

The user pushed all the right buttons, but the code's broken. This is a bug, a fault the programmer introduced that the user can do nothing about (except try to avoid it in the future).

The user pushed all the right buttons, and the programmer didn't mess up. Fate's fickle finger intervened, and we ran into something that couldn't be avoided. Perhaps a network connection failed, we ran out of printer ink, or there's no hard disk space left. These are the most common forms of errors and, unfortunately, the hardest to deal with.

The simplest error reporting mechanism is: don't bother. This works wonderfully in the cases where you want your program to behave in bizarre unpredictable ways, and crash randomly.

If you encounter an error and don't know what to do about it, blindly ignoring it is not a viable option. You probably can't continue your work, and returning without fulfilling your function's 'contract' will leave the world in an undefined and inconsistent state.

Never ignore an error condition.

If you don't know how to handle the problem, then signal a failure back up to the calling code. Don't sweep an error under the carpet and hope for the best.

An alternative to ignoring errors is to instantly abort the program upon encountering a problem. It's easier than handling errors throughout the code, but hardly a well-engineered solution! [Though for some situations it can be the best solution - JAD]

The next most simple approach is to return a success/failure value from the function. What that value gets set to depends on: the number of ways a function may fail, the diligence of the programmer, and any project conventions. Most functions will return a boolean value, a simple yes or no answer. More advanced mechanisms enumerate the possible ways a function can exit and return a status value to signify this, known as a reason code. One of those reason code values will mean 'success', the rest represent the many and varied abortive cases. This enumeration may be shared across the whole codebase, in which case your function returns a subset of the available values. You should therefore document what the caller can expect.

Whilst this approach works well for procedures that don't return other computed values, passing error codes back with returned data gets messy. For example, if you have a function int count() that walks down a linked list and returns the number of elements, how can it signify a list structure corruption alongside that int return value? There are three approaches:

This approach attempts to manage the contention between a function's return value and its error status report. Rather than return a reason code the function sets a shared, global, error variable. After calling the function you must then inspect this status variable to find out whether it completed successfully or not.

The shared variable reduces confusion and clutter in the function's signature, and doesn't restrict the return value's data range at all. However, errors signaled through a separate channel are much easier to miss or to wilfully ignore. A shared global variable also has some nasty thread safety implications.

The C standard library employs this technique with its errno variable - it's a good example of why error status variables are a bad idea. Its use is fraught with peril, nowhere near as simple as a function return value. You must clearly understand the semantics of its operation: before using any standard library facility you have to manually clear errno. They never set a 'succeeded' value to errno. This is a common source of bugs, and makes calling each library function more tedious. To add insult to injury, not all C standard library functions use errno, so it is less than consistent.

A shared error variable is functionally equivalent to the previous reporting mechanism, but has enough disadvantages to make you avoid it. Don't write your own error reporting mechanism this way, and use existing implementations with the utmost care.

Exceptions are a structured language-level facility to manage errors. They help to distinguish the 'normal' flow of execution from 'exceptional' cases. When your code encounters a problem it can't handle at that point, it stops dead and throws an error message up in the air. The language runtime then automatically steps back up the call stack until it reaches some handler code. The error message lands there, and the program gets a chance to handle the problem.

There are two operational models:

The former model is easier to reason about, but it doesn't give ultimate control. It only allows fault handling (you can execute code when you notice an error), not fault rectification (a chance to remove the cause of the problem and try again).

An exception cannot be ignored. If it isn't caught and handled, it will propagate to the very top of the call stack and stop the program. The language runtime automatically cleans up as it unwinds the call stack. This makes exceptions a tidier and safer alternative to handcrafted error handling code. However, throwing exceptions through sloppy code can lead to memory leaks and problems with resource cleanup^[2]. You must take care to write exception-safe code. The sidebar explains what this means in more detail.

Code that handles an exception is distinct from the code that raises it, and may be arbitrarily far away. Exceptions are usually implemented in OO languages, where error messages can be defined by a hierarchy of exception classes. A handler can elect to catch a quite specific class of error (by accepting a leaf class), or a more general category of error (by accepting a base class). Exceptions can be the only error reporting mechanism available in certain situations - how else can you signal an error in a constructor?

Exceptions don't come for free; the language support incurs a performance penalty. In reality this isn't very significant, and is only ever seen in the presence of the exception handling statements. Exception handlers reduce potential for optimisation opportunities. Throwing an exception is an expensive operation, so they should only be used for genuinely exceptional events.

Signals are a more 'extreme' reporting mechanism - largely used for errors signaled by the execution environment to the running program. The operating system traps a number of exceptional events, like a floating point exception triggered by the maths coprocessor. These well-defined error events are delivered to the application as a 'signal'. A signal interrupts the program's normal flow of execution and jumps into a nominated signal handler function. Your program can receive a signal at any time, and the code must be able to cope with this. When the signal handler completes, program execution continues at whatever point it was interrupted.

Signals are almost the software equivalent of a hardware interrupt. They are a Unix concept, now provided on pretty much every platform (a basic version is a part of the ISO C standard). The operating system provides sensible default handlers for each signal (some of which do nothing, others abort the program with a neat error message). You can override these with your own handler.

The defined signal events include: program termination, execution suspend/continue requests, and maths errors. Some environments extend the basic list with many more events.

You determine whether a function failed by looking at its return code. This failure test is bound tightly to the act of calling the function; by making the call you are implicitly checking its success. Whether you do anything with that information is up to you. [Though I am working on a proposal for C++ that would allow the author of a function to specify that the return type could not be ignored. - JAD]

After calling a function which sets an error status variable, you must inspect this variable. If it follows C's errno model of operation you needn't actually test for error after every single function call. Reset errno first, then call any number of standard library functions back-to-back. Afterwards, inspect errno. If it contains an error value, then one of those functions failed. Of course, you don't know which one fell over, but if you don't care about that level of detail, this is a slightly streamlined error detection approach.

If an exception propagates out of a subordinate function, you can chose to catch and handle it, or to ignore it and let the exception flow up a level. You can only make an informed choice when you know what kinds of exception might be thrown. You'll only know this if it's been documented (and if you trust the documentation).

Java's exception implementation places this documentation in the code itself. The programmer has to write an exception specification for every method, describing what it can throw; it is a part of the function's signature. Java is the only mainstream language to enforce this approach. You cannot leak an exception that isn't in the list, the compiler performs static checking to prevent this from happening^[3].

There's only one way to detect a signal: install a handler for it. There's no obligation. You can choose not to install any signal handlers at all, and accept the default behaviour.

it came from (which is quite distinct from where it's going to be handled). Is the source a core system component, or a peripheral module? This information may be encoded in the error report, or else we know what function was called and can figure it out manually.

you were trying to do. What provoked it? This may give a clue toward any remedial action. We probably only know this from our understanding of the error's context - you know what function was called. Error reporting seldom contains this kind of information.

it went wrong, and the nature of the problem. This only makes sense in the context of the error's source, and what was being done. You need to know exactly what has happened, not just a general hand-wavy class of error. It's important to know how much of the erroneous operation completed - all or none are nice answers, but generally the program will be in some indeterminate state between the two.

it happened. This is the locality of the error in time. Has the system just failed, or has a two-hour old problem only just been spotted?

of the error. Some problems are more serious than others, but when detected one error is equivalent to any other - we can't continue without understanding and managing the problem.

The level of severity is usually the caller's opinion, based on how easy it will be to recover or work around the error. If it's not a big deal, the strategy may just be to live with the problem. If it affects core functionality this isn't acceptable; the code must do everything possible to fix the problem and continue as if nothing happened.

to fix it. This may be obvious (e.g., insert a floppy disk and retry), or may not (e.g., you need to modify the function parameters so they are consistent). More often than not we have to infer this knowledge from the other information collated.

Handle each error as you detect it. Since the error is handled near to its cause you retain important contextual information, making the error handling code clearer. This is a well-known self-documenting code technique. Managing each error near its source means there's less code which control passes through in an 'invalid' state; too much of that leads to very dense logic.

This is usually the best option for functions that return error codes.

Alternatively, defer error handling as long as possible. This recognises that code detecting an error rarely knows what to do about it. Often it depends on the context it is being used in: a missing file error may be reported to the user when opening a document, but silently handled when hunting for a preferences file.

Exceptions are ideal for this approach, you can ignore an exception until you know how to deal with the error. This separation of detection and handling may be clearer, but can make code more complex. It's not obvious that you are deliberately deferring error handling, nor is it clear where an error came from by the time you do handle it.

In theory, it's nice to separate 'business logic' from error handling. Often you can't, as cleanup is necessarily entwined with that business logic. It can be more tortuous to write the two separately. However, centralising error handling code has advantages: you know where to look for it, and can put the abort/continue policy in one place, rather than scattered through many functions.

Any reasonably large project should already be employing a logging facility. It allows you to collect important trace information, and is an entry point for the investigation of nasty problems.

The log exists to record interesting events in the life of the program, to allow you to delve into the inner workings and reconstruct paths of execution. For this reason all errors you encounter should be detailed in the program log; they are one of the most interesting and telling events of all. Aim to capture all pertinent information - as much of the list above as you can.

For really obscure errors that predict catastrophic disaster, it may be a good idea to get the program to 'phone home' - to transmit either a snapshot of itself, or a copy of the error log, to the developers for further investigation.

What you do after logging is another matter...

A program should only report an error to its user when it doesn't know what else to do. The user does not need to be bombarded by a thousand small nuggets of useless information, or be badgered by a raft of pointless questions. Save the interaction for when it really is vital. Don't report when you encounter a recoverable situation. Log the event by all means, but keep quiet about it. Provide a mechanism for the user to read the event log if you think they might care one day.

There are some problems that only the user can fix. For these it is good practice to report the problem immediately, to give the best chance to resolve the situation, or to decide how to continue.

Of course, this kind of reporting depends on whether the program is interactive or not. Deeply embedded systems are expected to cope on their own.

Sometimes your only course of action is to stop immediately. But not every error spells doom. Some are quite expected. If your program saves a file, one day the disk will fill up and the save operation will fail. The user expects your program to continue faultlessly under these situations, so be prepared.

If your code encounters an error and doesn't know what to about it, pass the error upwards. It's more than likely your caller will have the ability to recover.

I only include this for completeness. Hopefully by now you've learnt to scorn the very suggestion of ignoring an error. If you choose to forget all about handling it, and to continue with your fingers crossed: good luck. This is where most of the bugs in any software package will come from. Ignoring an error whose occurrence may cause the system to misbehave inevitably leads to hours spent debugging. Ignoring errors does not save time.

You'll end up spending far longer working out the cause of bad program behaviour than you ever would have spent writing the error handler.

You can, however, write code that allows you to do nothing when an error crops up. Is that a blatant contradiction of what you just read? No. It is possible to write code that copes with the world not being right, that can carry on correctly in the face of an error, but it often gets quite convoluted. If you adopt this approach, you must make it clear in the code. Don't risk it being misinterpreted as ignorant and incorrect.

When a subordinate function call fails you probably can't carry on, but don't know what else to do. The only option is to clean up, and propagate the error report upwards. You have options. When propagating an error you can either

Ask yourself this question: does the error relate to a concept exposed (directly, or indirectly) through the module interface? If so, it's OK to propagate that same error. Otherwise, recast it in the appropriate light, choosing an error report that makes sense in the context of your module's interface.

This is a good self-documenting code technique. For example, you can catch and wrap up exceptions, or return a different reason code to the one you received.