Thursday, April 06, 2006


A coworker lent me an amazing book: Framework Design Guidelines. Yes, yes, it's an MSFT book and talks about the .NET platform and is thus, by definition, evil. But it's still a phenomenal book and full of bits of wisdom.

Each time I've picked it up, I've wish I could condense it into a cheat sheet and paste it to my monitor while coding. The following excerpt is not exactly groundbreaking, but something I wish I could remember when I design APIs:
It's OK for exceptions to have a property returning some kind of error code, but I would be very careful about this. Each exception can carry two main pieces of information: the exception message explaining to the developer what went wrong and how to fix it and the exception type that should be used by handlers to decide what programmatic action to take. If you think you need to have a property on your exception that would return additional error code, ask yourself who this code is for. Is it for the developer or for the exception handler? If for the developer, add additional information to the message. If for the handlers, add a new exception type. (pp. 184/185)

(I'm sure I'm guilty of adding a stupid error code to an exception)


Amar Zumkhawala said...

error codes in the error message are great shortcuts to more documentation on the problem. bea provides with each error message an error code, and it's online help documentation facilitates self-help by organizing the navagation system around error codes. for systems with many external customers, it's works well and created a great user experience for me when I used their Tuxedo product.

hemantbhanoo said...

amarz: I can see how some errors probably need a few paragraphs or a page worth of documentation to explain them. But I've found that most times, it's not that long. Maybe two sentences at most. And rather than fix the cryptic error message, we were thinking about a web-based system where you could paste in the error-message/code and get back detailed info about what to do, how to fix it, etc.
At amazon, where it's possible to deploy new software in a matter of weeks, it would've been smarter to just go update the source code, instead of making developers copy/paste the error into some webpage to get detailed information.
That said, I can see how the combination of useful messages and error codes could help a software product where distribution is not a matter of "pushing out new software" to machines that you own.