Each programmer has to deal with error mesages in some way. Either we have to check our data (and possibly raise an error/exception) or we are using libraries and have to deal with error messages or exceptions that are raised in these libraries. The purpose of this post is to point out how meaningfull error messages can save you time. Either your own time (by avoiding answering support questions) or your own debugging time.
So how can an error message save or waste time? Imagine the situation where you try to open a file and all you get is an error. What do you do next? I guess you’ll probably check if you’re trying to open the correct path. Maybe you did, then you possibly check if the permissions are okay, if you’re trying to open a directory or a file, etc until you found the problem that is causing the error. Actually this can be quite some wasted time – why? Becasue you’re doing all the stuff that the system already checked. The system decided that one of the condidtions failed and exited. So – shouldn’t the system just TELL the exact reason? And even better: shouldn’t it also just tell you a possible solution? Well – actually I do not blame “the system” but the guy who write the line that threw the error without any further information. Everytime I get an absolutely uninformative error I think “was it really so damn hard to add one more line of code that just mentions WHAT went wrong?!”.
Assume the situation where you try to open a file with the path being configured in an external config.properties file.
I think the quality of an error message can be categorized in one of the three categories:
- Reporting: The system just reports that there was an error.
Example:IO Exception occured. - Informing: Same as 1, just with more information.
Example:IO Exception occured while opening file: <filename>, null=false, exists=true, is file=false, is directory=false, readable=false, writable=false - Supporting: same as 2 with additional information of how to solve the problem.
Example:IO Exception occured while opening file: <filename>, null=false, exists=true, is file=false, is directory=true, readable=false, writable=false; Was the pat set correctly in config.properties?
In the past weeks I have seen very useful error messages in Google’s Android (“… Have you declared this activity in your AndroidManifest.xml?”) or in twitter4j (Displaying a shortURL to an FAQ page explaingin a very common error).
Bad examples are plain NullPointerExceptions when 3 parameters were checked, one of them was null and the according is just followed by a throw new NullPointerException so that you even did not recognize from the message WHICH parameter was null.
Conclusion: Please write robust code and please provide helpful and supportive error messages to the folks using your code!