Tip of the Iceberg

1 - I <3 Tim!

Perfect...you are absolutely right. AND...For all of the application developers out there, we should be doing the exact same thing that Tim talks about. Our errors should tell the users what to do in a clean and easy to understand manner.

That last sentence should be blasted from the rooftops. Amen!

2 - Yikes Tim, next you're going to tell me you don't like the NSD prompt that is too large to see the OK button when the 8.5 Client crashes!

I'll assume that they know the user will just smash their keyboard in frustration, and thus hit the spacebar which should trigger the OK...

3 - The respect I have for you just went up.

How on earth were you able to figure that out as a work around?

4 - Ok, I get what you're saying but... you can't seriously suggest that IBM hardcode knowledge of a workaround to a bug they probably didn't know exist.

What do you do in your apps to cover the unexpected? The best I've been able to come up with thus far is prompting with "There was an error "Division by zero". What did you do to create this error?" and then logging that and a stack trace.

5 - @John - Perhaps my example message was a bit overzealous. If they truly never encountered this scenario during testing, as you say, they don't know it's a bug, so they aren't aware of a workaround, so there's no way they can possibly provide instructions for implementing said workaround.

On the other hand, they know at least two things about what went wrong:
1. The user tried to edit a design element, but the editor failed to load.
2. The reason the editor failed to load is that some reference (index) to something couldn't be resolved. Whoever coded this (and, again, it's likely that the displayed error is in an Eclipse layer, not in a Designer-specific layer) had some inkling of what it actually means when an index cannot be found while trying to load an editor, and could have at least provided more user-friendly detail about the nature of the problem, if not a workaround... which is more noticeable when your end users are also developers: give them just a tiny bit more context and they'll probably be able to hack their way through the problem.

As far as dealing with the unexpected is concerned, there are two key principles I try to adhere to:

1. Test, test, test, test, test, test, test. And then, of course, test some more. This particular error was not the result of some wacky mind-bending "you'll never actually encounter this while developing a real XPage" scenario. I wasn't building something experimental at home during a bout of insomnia. I was onsite at a client, building a fairly straightforward interface. Yet it turns out that nesting sections without splitting each layer into a separate custom control tends to piss off the rendering of the Design tab when reopening the element. No big deal, I'd been planning on creating that element hierarchy eventually anyway. Once I did, the error went away for good. But, as much as I love XPages, Designer itself is chock full of behaviors like this, where something wasn't tested as thoroughly as I'd expect from IBM, and the result is an error message that offers cryptic or no advice on how to resolve or avoid the problem... have you seen the one that says an error occurred, and when you click the provided "Details" button, the additional detail displayed just says "Error"? Another perfect example. If you've got error handling that displays an error summary and error details, and both just say "Error", and that handling routine ever gets triggered, the release was shipped before its time. Yet another reason why I wish they'd separate the client/Designer release schedule from the server release schedule entirely (since they tend to alternate between client-focused and server-focused releases anyway), but that's a discussion for another day.

2. Throw like a girl. This isn't a sports reference; rather, an observation that women tend to be more detail-oriented than men. The stack trace above gives us at least some clue as to what went wrong: at the point of failure, Designer was trying to draw some 2D shape. We don't know exactly what shape or why, but a hint lies three layers up in the SectionEditPart.addChildVisual method: the code was trying to render some portion of a visual representation of a section control, and something went wrong. But they failed to throw enough information up the stack for the actual error display to "know" what went wrong... so it told me all it knew - that some index wasn't found. Which doesn't tell me what I need to do differently, even though in some layer of the code, it "knew" what it was unable to do.

As you know, but other readers might not, one advantage Java has over LotusScript is a far superior error handling mechanism that adheres to the throw/catch model. Every method can define what types of exceptions it throws (which are typically treated as errors, but could be any deviation from the norm, including input validation failures, if that's how you choose to respond to them), and every method that calls methods that could potentially throw a specific type of exception must either catch them (in other words, provide a final response to the exception) or specify that they, in turn, throw the same type of exception. In the latter approach, if method A calls method B, which calls method C, and method C throws an exception that method B does not catch, it stops its own execution and throws the same exception up to method A. At some point the thrown exception must be caught and responded to or everything explodes. In the example I provided, Designer did not crash. Ergo, the error message that was displayed was the result of a deeply thrown exception finally being caught... which implies that somewhere in that stack, not enough detail was provided in the exception that was thrown for an intermediate layer to catch it and respond gracefully without treating the exception as a true error, or even for the eventual error message to display any meaningful information about what caused the exception. That's why it's so important to define custom exception classes that store detailed contextual information: so that most exceptions never become errors in the first place, and when they do, the user is informed of the best way to proceed.

6 - Your response is worthy of it's own post, IMHO.

So... translating that to a best practice, one would write error handling code to not only capture/bubble up a stack trace but also capture/bubble up possible actions the user should take to remedy the problem, so that if the error gets to the top, the main subroutine has what it needs to log and a list of things to tell the user to try?

Or were you thinking something different?