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.

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.

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

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.

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.

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.