Error Checking

Should error checking be included in printed books that cover code? Is it worth adding an extra 10% of text in order to ensure that programmers will not forget to check for error conditions? And ultimately, who's responsibility is it to check for errors? These questions bear a multitude of implications. In a recent discussion on the Editor's List, four editors contemplated the pros and cons of including error checking in print texts.

Andy Oram:

I'd like some comments on this.

Authors of programming texts follow a common tradition: they eliminate error checking after each function call in their programming examples, in order to save space and make examples look cleaner. To atone for this violation of good programming practice, they always request absolution through the appeal: "Don't do what I've done; make sure to always check for errors."

But how many readers notice the appeal and take it to heart?

In the November 2004 ACM Queue magazine, Microsoft researcher Brendan Murphy tells us just how little we dare overestimate the sophistication of our readers:

...analysis of many driver crashes showed that the root cause was that the drivers did not check for error conditions following a system call. In discussions with the developers, they said that code had been copied from help files in Microsoft's Drivers Development Kit and MSDN online documentation. The original documentation was written to provide succinct examples of how to use the system calls annd so lacked error handling. The fix: the documentation has been rewritten to include checks for error conditions.

My first reaction was to say, "Let Microsoft go ahead and add extra bulk to their online documentation; I'm never going to waste space on error checking in a printed book." Then I began to wonder how much space that would actually require.

So, in my typically scientific manner (an impulse from the spinal column), I grabbed the most recent manuscript I had received for a chapter in a programming book. It's 40 pages, covering 65 function calls, contained 56 examples that issued a total of 176 calls.

I assume that to insert error checking would require one extra line of code for each function call. The call would be wrapped in an if statement, and a subsequent fprintf to standard error would take up the extra line. (Some C programmers use more complex coding structures, but they're optional.) In C++ or Java, the extra line might be devoted to a throw; in Perl, to a warn or die statement.

Since an 8x11 page commonly contains about 47 lines, adding one line for each of the 176 calls would increase the 40-page document by 4 pages, or 10%.

Truly defensing coding involves a lot more than checking return values, of course, but it depends so much on the environment and application that we can't be responsible for holding the reader's hand.

So is it worth adding 10% to a text in order to save a substantial subset of readers from spending hours tracking down preventable, hard-to-diagnose errors? I'm leaning to think that it is. The cost may not be as great as my crude calculation suggests, because sometimes one can ignore an error (such as when issuing a call that retrieves an error string) or combine calls, especially in languages with "try" blocks, and let a single error check cover several calls.

Unix snobs may have closed the message window at this point with the excuse, "Microsoft users are less sophisticated than our audience." But we want those users.

The other objection I should take on is that the error checking statements muck up the code and make it harder to read. But this is a subjective judgement that becomes moot when readers see enough of this error code; programmers become accustomed to looking at common programming idioms and learn to take them in as a gestalt. An experienced programmer, for instance, would scan the following relatively easily:

/(<[^>]*)$/ and ++$in_tag>1 and warn "No nested tags: $1";

although he or she would also rewrite that code at the first opportunity.

Similarly, a non-native English speaker might notice that the title of this mail message contains three words ending in "ing" that represent three different parts of speech (a verb, a noun, and an adjective); native English speakers probably skimmed right over that syntactic twist.

In fact, the tendency to latch onto common syntactic patterns is a strong reason for including error checking in examples: you want to get readers used to seeing the syntax and get them to expect it in all the code they write or maintain.

Furthermore, authors commonly include error checking to make sure their examples are correct; if you ask them to strip out the error checking before including the examples in the book, you introduce another manual step that has the potential for introducing errors.

Daniel Steinberg:

I was on a JavaOne panel with Joshua Bloch, who stressed how important this published sample code is. We also had a java.net blogger write about his experience tracing an error which came back to faulty code in the Java Almanac that was cut and pasted.

I think Andy raises an important point--but the answer often depends on how someone is using your code. It is pretty standard in Java texts to have

try{ //something
}
catch (SomeException e){
   e.printStackTrace(); //replace this with error handling
}

The person writing the code snippet can't possibly know how the end user wants to use this code and what they want done in the case of an exception. Bad techniques are to catch an Exception instead of SomeException--that may sneak by a reader--or to swallow the exception in main(). So we need to show where exceptions can and should arise, but we may not be able to specify handling them.

Maybe we need an @example annotation in Java that triggers the user to fix the example before using it in production.

Bruce Epstein:

Adding 10% to a book is considerable. There has to be a certain amount of caveat emptor. It also depends on the audience. If you are teaching programming, then error checking should be taught, but you first need to teach basic syntax, what a return value is, etc. So some examples might include error checking and others may not.

Certainly, if you're teaching how to program realtime nuclear power plant monitoring code, you damn well better include the error checking in every example.

I understand there is a large middle ground of programmers who are neither novices nor experts. I think novices would be overwhelmed by trying to learn from examples full of lots of error-checking code, and experts should be smart enough to add error checking even if it isn't shown in the example. For the middle ground, there are many things we could/should teach them about programming, but every book can't be a computer science course. Must every book teach OOP, design patterns, unit testing, and how to use CVS? I think not. Will a certain number of programmers and projects fail miserably when, say, they forget to back up their code base? Yes, but we'd never get anywhere if we also cater to the lowest (or highest) common denominator.

Macromedia includes error checking and lots of extraneous features in the components (widgets) they provide. They are universally considered bloated, hard to modify, and impossible to teach/learn from. My point is that robust, deployment-ready code usually differs considerably from teaching code, unless you are teaching about error checking and robustness. Should Cookbook examples include error checking? I think so, because the whole intent of a Cookbook is to provide cut-and-paste solutions. But that doesn't always apply.

My approach has been a hybrid:

1. I advise authors not to include error checking at every turn, especially if they are trying to teach something else. But many examples include error checking (especially when the results must be handled in a callback).

2. I include several warnings such as "This is not robust, deployment-ready code. See the online examples for the full version."

3. I include sections, often entire chapters, on error handling and debugging. For example, Essential ActionScript 2.0 includes a chapter on try/catch/finally and how to decide what level of granularity is appropriate when designing your error codes.

4. I always encourage authors to include full error checking in online examples.

Keep in mind that Flash/ActionScript programming tends to be used in low-risk situations. The best balance is one tailored to your audience and the programming language's common usage.

My two point five centavos.

P.S. People writing drivers should know how to check error/return codes and should do so. Yes, Microsoft should include error checking in their examples, but it is inexcusable for these developers to be cutting and pasting code and not adding error checking if it is absent.

The best defense is a good interview before hiring. Ask the developer to write/correct some code and see if s/he includes error checking. To be fair, you should ask him/her to write a short, robust example. If an interviewee doesn't know that the word "robust" is a synonym for "include error checking," don't hire him/her.

Marc Hedlund:

I strongly agree with your point of view. I've caught cases of programmers cut & pasting code from websites, and that code not having various properties that you would otherwise want (including error handling)--even in great programmers that have been ruthlessly interviewed. Everyone gets to the point of having a bad deadline and looking for the nearest available solution.

Return to: From the Editors List