2004-07-19

Error returns are always worth checking

You can find that phrase in Sun's The JVMPI Transition to JVMTI, which talks about the new interface to Java VM internals in Java 1.5.0 that replaces older interfaces.

It sounds quite different if you read it in context, though. The full quote is:

Note that all of the JVMTI error return handling and checking code has been left out of the above example. Do not do this in real life; those error returns are always worth checking.

I'm sure you've seen that said so many times before it almost seems natural. But I think it's helpful to have it translated, so here are the subtitles:

Note that this exact code will be copied & pasted all into software all over the world. This is real life. Those error returns will never be checked.

The usual excuse for not showing error-handling code in examples is that it obscures what you're trying to show. People actually say that. As if they don't realize that what they're saying is "we made such a mess of the interface that it's really nasty to use; it's not too bad if you remove all this fundamentally important stuff that makes the difference between a proof of concept and a shippable application and pretend it's not needed".

To be clear: I haven't looked at JVMTI yet. For all I know, it's a great API and their only mistake was missing out the trivial, clean error-handling code on this web page. It's also the case that what they're doing is intricate enough that you'll probably have to take one of their full examples to get anything working, and the web page implies that the proper error handling is present there. They just happened to say the wrong thing at the wrong time, and it set me off!

The attitude that "it's only example code" really annoys me. Example code is exactly where you have to be on your best behavior. Example code is what a lot of people learn programming by fiddling with, and example code gets pasted in to a lot of shipping applications. And yet you look at it, and you see missing error-handling and heinous levels of duplication.

The main thing I learned from O'Reilly's "Building Cocoa Applications" is that the authors can't program. (Scott Anguish and friends can, though, so buy their "Cocoa Programming", published by Sams, instead.)