How to write good error messages
An anonymous javaBlogger posted about crummy error messages in many common frameworks today. His complaint was with messages like this:
- Wrong string format
- Cannot open file
- Unable to contact server
And proprosed changing them to include the offending input:
- Wrong string format in state code: "WI_1234"
- Cannot open file: my.settings
- Unable to contact server: your.mom.com
I would say go even further. Explain exactly why the input failed and what input is expected. For example:
- Wrong string format in state code: "WI_1234" -- state codes must be in the format of: "AB:1234" and are case sensitive.
- Cannot open file: my.settings -- the file was not found, make sure its in /path/to/resources/.
- Unable to contact server: your.mom.com - returned error code 500 -- ensure that the server can respond to HTTP requests on port 8080
Put your self in the role of the user who is just starting out with your framework. And by “user” it could be a programmer extending your framework, a teammate using your interface, or Joe User trying to use your GreaseMonkey script. Imagine what would be helpful for someone who knows absolutely nothing about the inner workings of your program, and what sort of information would be helpful when things go wrong. Graham wrote “Empathy is probably the single most important difference between a good hacker and a great one.” So have some empathy, and spend a little more time on those error messages.