The Importance Of Error Messages
I had a good laugh on Friday as I ready the Pop-up Potpourri: Mayday Edition article over on The Daily WTF. As one person commented: ”These make TheDailyWTF worth existing.” So funny. More so since these pop-ups come from actual applications. I have always believed that if you are going to display some sort of error message, the message should really only display a brief explaination of what happened (ie. ran out of disk space), what didn’t happen (ie. file wasn’t saved) and what the solution is, all from the user’s perspective. The user doesn’t care about internal error numbers or stack traces or anything else that relates to debugging of any kind. All the user wants to know is how can I fix the problem and move on with what I’m trying to do. Everything else is stuff that should be in the application’s log file.
That brings me to log files. I ran into a small error this weekend that caused me to sit down and say “what was I thinking?”. And before you start into me about not using a logger, such as log4j, forget it; this application predates log4j. And not only that, there are some instances I can think of where you may want your logging to go to stdout. I have slowly been migrating the logging over to log4j but there are still a fair number of calls to System.out.prinlnt(). Anyway, once again, I digress. I had been tinkering in the code of an application, adding some new features. But recently I had also been cleaning up old code, mostly instances where methods had been deprecated. I was testing something out, when I saw a string of these in my console logger:
UTF-8
UTF-8
UTF-8
UTF-8
The offending code it turned out was a result of a change I made due to a deprecated method within URLEncoder. The new method requires an encoding scheme, which The World Wide Web Consortium Recommendation states should be “UTF-8”. But what I had instead was “UTF-8 ” (notice the extra space) within code similar to this:
try {
userList.append(URLEncoder.encode(lastUserStr, "UTF-8 "));
}
catch (UnsupportedEncodingException uee) {
System.out.println(uee.getMessage());
}
The end result was that an UnsupportedEncodingException was being thrown and the error message associated with that exception was my invalid encoding scheme. Unfortunately, in a console logging window, that extra space doesn’t show up, so from a developer’s perspective it looks like UTF-8 isn’t supported. And that simply wasn’t the case. Since I haven’t got this particular class set up with log4j and not wishing to introduce any major changes at this point, I replaced the offending code with something like this:
try {
userList.append(URLEncoder.encode(lastUserStr, "UTF-8"));
}
catch (UnsupportedEncodingException uee) {
System.out.println("Unsupported encoding: " + "[" uee.getMessage() + "]");
}
So next time you are writing a error message, think aobut who the reader of the message will be and ensure the message is written from that person’s perspective. And don’t try and write a message that will satisfy multiple types of people.
Mon, 15 May 2006 22:21 Posted in Programming
