Error messages - forgotten customer serviceDoing an exception handling correctly is hard. We all know it. Writing good error messages is not hard, but we still don't do it. Good error message can reduce maintenance costs and it improves the quality feeling of your product greatly.
In my work I frequently use an Oracle database. Oracle has some very good things in it's database products, but error messages ain't one of those. Let's see few examples. First two are picked up from this list: Top 40 Most Searched For Oracle Errors
1. ORA-12154: TNS:could not resolve service name
This is quite technical exception, but it's usually caused by the same reason. Oracle documentation points into right direction, but why it's not put into error message?
Cause: Oracle Net could not locate the net service name specified in the tnsnames.ora configuration file.
So, the same error could be transformed into something like:
ORA-12154: tnsnames.ora configuration file is missing service definition for MY_COOL_TNS_NAME. Check file from path C:\Oracle\product_11\Admin\Network\tnsnames.ora.
2. ORA-00911: invalid character
What this message really give u?. Receiving this message from a 500 hundred lines of PL/SQL script can make a big man cry. Documentation provides little help, but not much.
Cause: identifiers may not start with any ASCII character other than letters and numbers. $#_ are also allowed after the first character. Identifiers enclosed by doublequotes may contain any character other than a doublequote. Alternative quotes (q'#...#') cannot use spaces, tabs, or carriage returns as delimiters. For all other contexts, consult the SQL Language Reference Manual.
So we may have non-ASCII character at the identifiers name or not. This error is way too generic, exception handling should be improved to give a more accurate reasons. I think they could examine the given input and provide a more accurate error message, or at least give more specific hints.
3. ORA-00972: identifier is too long
Error message is saying that we have an identifier which is too long. I'm not sure, but I'm guessing that if we had two or three identifiers with too long names. We would receive a same error. If we look-up the documentation of Oracle product. It gives us a tip:
Cause: An identifier with more than 30 characters was specified.
Action: Specify at most 30 characters.
ORA-00972: An identifier MY_DATABASE_COLUMN_WITH_SOME_INSANE_NAME is too long. Maximum length is 30 characters.
Great error messages has two important parts. It explains why error has occurred and tells you how to fix it, or at least gives some hints how tackle the problem. It's not always necessary to point exact place where problem might lay, but giving a direction is far better than saying nothing, even it's not real source of error. It still points to one possible solution and remember, these messages can be improved over time!
If it feels hard to write a good error message, or there is too much to cover in one error message, maybe your exception handling isn't accurate enough?
Rules to handle errors
1. Handle as accurate types of exception as possible
2. Remember rules for good error message
3. Make sure errors are recognizable from warnings.
4. If possible, provide additional info for error.
I first created this blog post because I was frustrated about error messages of an old Angular version. Luckily things are getting better and Angular is now providing links with additional info among errors.