Designing Error Messages

As an A-380 pilot, a warning which says that bit 9 of data package 98887 sent through your ARINC 429 data bus is unexpectedly 0, will keep you busy for a while searching for the actual problem. On the other hand, a nicely crafted error message which states "Engine #3 is on fire" will give you a much better idea of what's currently happening on board.

What's so cool about being a pilot is that you have checklists and procedures for almost any situation. Your airborne computer will most likely suggest to activate the fire extinguisher and let the remaining engines take over the load of #3.

Funnily most developers – and yes, especially framework designers – don't care much about error messages. Most checks are done at that level a possible error my occur – and the message will state just that, something like "Unexpected Type" or "Invalid Argument Bckblst::$fsPtr". Really helpful.

FLOW3 can't really acquit itself from this practice, but it's getting better and better. The strategy (wow, a strategy ;-) we have for error handling and especially for messages is to first and foremost make sure to implement safe guards which protect the API from causing fatal errors. The corresponding messages for these exceptions are very low level, but hopefully telling enough to spot the rough location of a problem. The messages you, a developer using FLOW3, will hopefully see however, are designed differently: They should tell

  • what went wrong
  • where it went wrong
  • what was expected
  • and what you can possibly do to solve the problem

Furthermore we use a unique number (the unix timestamp of the time we were implementing the error message) so you can easily find the related source code and communicate with other developers about the thrown exception.

There's a lot more to say about error messages, especially when it comes to the TYPO3 Phoenix UI. A nice introduction into this topic is – you wouldn't expect that – a guideline by Microsoft. It features many bad and some good examples for communicating all kinds of failures.

Speaking of burning engines – did your operating system ever confront you with an lp0 on fire error?

Leave a reply