Error Messages Are for the Users

A few days ago, I ran across the following code snippet:

if len(sys.argv) < 2:
    print 'Need at least one argument'
    exit(1)

From a developer’s point of view, this code is fine: it stated that a required argument is missing. However, from a user point of view, the message does not make any sense. Sure, the message tells the user that a required parameter is missing, but what is it? A file name? A directory location? An URL? An email?

Even if the program is written for private use, hence the developer is the sole user, error messages like this does not help stating the real problem. Many times, I found myself having to look into my own code to learn of its usage. What about the situations when the users do not have access to the source code, or if they are not technically savvy enough to find out?

When writing code, keep the users in mind and tailor error message from their point of view. The above then could be written as:

if len(sys.argv) < 2:
    print 'An email address is required, but missing.'
    print 'Usage: myprogram email'
    print 'Example: myprogram foo@bar.com'
    exit(1)

Below are some error messages which I encountered (some I even wrote, shame on me) and suggested changes:

  • Socket is NULL ==> Cannot connect to host $hostname, please check for correct host name, or port number
  • File not found ==> File $filename does not exist, please check for correct path
  • An error has occurred, program quits ==> Too vague to suggest, the program should investigate the cause of failure and report a more detailed message.
  • Login error L01253 ==> Something like: Login error — wrong user name or password.

In conclusion, while providing a more detailed error message means extra works for a developer, it makes for a better user experience. The next time you see a vague error message, either fix it, or report to the developer.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s