Nick Johnson

There are a lot of things I've come to love about Toplink over the years, and by the transitive property I love them in Glassfish. But there's one part of Toplink I absolutely cannot stand: the error messages, or lack thereof.

Consider this one: "Unknown abstract schema type [Foo]" where "Foo" is some class. What does that actually mean? It means Toplink couldn't find a class called Foo defined in persistence.xml. So why couldn't the bastards just SAY that? Why did they have to say "unknown abstract schema type"?

Attention Toplink Authors, or at least those of you who write these fucked-up error messages. I have a little task for you. There's something I want you to do. Ready for it?

Write some fucking decent error messages.

Seriously though, this got me thinking about error messages- what kinds of error messages I find useful and what sort of error messages I hate. Obviously I hate messages like "unknown abstract schema type". Worse still is the *absence* of error messages (aka, the "silent failure") and only slightly better is the NullPointerException (or any other exception with a broad, generic name) with the stack trace.

So what makes a good error message good and a bad error message bad? I have narrowed my scope to four things: Context, Clarity, Detail and Action-ability.

• Context: this error didn't just happen out of the blue. What was the program doing when the error occurred? Was it trying to locate a class defined in persistence.xml? Was it trying to find META-INF/persistence.xml on the classpath? Was it attempting a network connection? A disk write? Was this action part of some larger task? Just what was going on in the system when the error occurred?


• Clarity: errors should be concise, plain-English descriptions of the fault condition that give the developer (or the end user) a concrete idea of what actually went wrong. "Unknown abstract schema type" doesn't do that. "Unable to find a <class> entry for [Classname] in persistence.xml" would give a much clearer idea of what went wrong.


• Detail: hand-in-hand with clarity, the error must give enough detail so that the problem can be resolved, but not so much detail that the user or developer is buried in irrelevant minutia. "Class not found" isn't enough detail. "Unable to locate class net.spatula.news.GoatCheese on the classpath" is better. Along with Clarity, "Unable to locate class net.spatula.news.GoatCheese during initialization" is better still.


• Action-ability: this goes beyond simply giving an error message to which the developer or end-user can respond with some action; it's better still when the error message can offer suggestions. I was pleased to see this show up in PostgreSQL 8.1. Not only did it tell me what my error was, it offered a HINT about what I might do to correct it. How much easier my morning might have been had Glassfish Persistence said, "Could not find an entry for class [Article] while initializing mappings. Make sure the class is specified by EJB or by a <class> entry in META-INF/persistence.xml."

Yeah, it's a little more work for the framework developer, but it makes the framework a lot more usable and developer-friendly.

Labels: software