The bane of error messages

Thoughts By 5 years ago

Error messages occur in a program in order to inform users about something going wrong with a program, they are sometimes cryptic about what the actual problem is (for example error numbers that correspond to specific points in code that a software engineer would be able to track down) and other times they are overly transparent (relaying technical jargon to a user doesn’t help them).

Having said that, it is vitally important for error messages to occur, users should really have a right to know if something goes wrong in the software they are using. An ideal error message should contain a number that lets the software developer know where in the code the error occurred, and a brief description (for example if the issue is a connectivity issue state that to the user, but don’t start talking about corruption in the TCP packets).

People don’t place enough importance on error messages, they are especially important in the development environment, a badly worded error message can sometimes take hours for a developer to fix. An hour that could be easily avoided if the error message contained helpful information. For me, 2 examples stuck out to me as almost deliberately unhelpful error messages, and they are both made by leading software developers (proving that no matter how big you are, mistakes can be made):

Class UIShadowView is implemented in both /System/Library/Frameworks/UIKit.framework/UIKit and /var/mobile/Applications/6B523B2B-2F45-4D2F-AA36-7C6DCA6ACE94/AppX.app/AppX. One of the two will be used. Which one is undefined.

This error (as a I later learned) showed that using the objective c class UIShadowView in one of my apps was not applicable due to the name being reserved in the UIKit framework, however the fact that which one will be used is undefined is a ridiculous notion. The software will eventually have to pick one, and when it does I should know about it, just saying ‘which one is undefined’ is useless for me as a software developer.

Error Domain=NSDictionary+xmlBinding Error Domain Code=6 “complex type ‘xType’: The content model is not determinist.

” UserInfo=0x2cbd80 {NSLocalizedDescription=complex type ‘xType’: The content model is not determinist.

}

This error was produced by TinyXML for an XSD, for what purpose I cannot remember, however most software developers aren’t philosophers so the use of the word “determinist” is unhelpful, instead of knowing immediately what to fix, developers have to spend hours looking up this error and squashing the bug that produced it.

In short, I encourage software developers to assign basic error numbers to their error messages, and a simple but brief description of the problem without using jargon or overly complicated words.