One of my least favorite errors is ORA-01775: looping chain of synonyms. This often means that you’ve referred to something that can’t be found for one reason or another – a table doesn’t exist, a table is owned by a different user, there actually is a synonym loop…

The nice thing about Oracle error messages is they all come with descriptions to tell you what’s going on and numbers so you can look up more information. The bad thing is that the messages aren’t necessarily all that helpful, and the error may be too general to let you know exactly what’s going on, as in the case above.

The action could not be completed. Ok, what do I do next?

Ok, what do I do next?

In 2013, I spent a good chunk of time going through the software I work on and looking for any error or warning messages that were not helpful. We used to have one internal error message that really meant you needed to have the Oracle Client Tools installed on your machine, but that wasn’t what it actually said, and we got questions about it pretty regularly. While those questions only took five seconds to respond to, it would have been a lot better for the message to actually be meaningful to the person experiencing the problem! Thankfully, we got those cleaned up so that now our error messages actually tell you what you need to do to resolve them.

This applies to help text as well; much of our help text has been rewritten to be actually, y’know, helpful. By definition, help text will be used by someone who’s not an expert in the software or problem domain, so it needs to be very clear about what’s expected of the user.

While this isn’t directly related to coding, it’s still something programmers should consider as part of usability. Someone has to use your software; part of your job is to make sure they can do so effectively. Include technical details if it’ll be helpful in debugging, but remember that every error, warning, or help box should make sense to the end user of the software. Give that person clear direction so that he or she knows what to do next, and doesn’t attempt to defenestrate the computer.

Never mind the looping chain of synonyms; just tell me you can’t find the darned table!