Error Messages

Error messages should consist of both the input being handled, and what the actual problem was, as precisely as possible. Many (most?) error messages are just of the generic form “an error occurred” (and even that exact message), without any further information.

To illustrate the difference, some examples, from least to most informative:

	invalid account data
	Email invalid
	Email address invalid
	Email address in invalid format
	Email address not in the correct format
	Email address not in the correct format: foo.bar@baz
	Email address "foo.bar@baz" not in the correct format
	Email address "foo.bar@baz" not in the correct format: invalid domain name
	Email address "foo.bar@baz" not in the correct format: "baz" is not a valid domain name.
	User name invalid
	User name invalid: john gallagher
	User name "john gallagher" not valid: invalid character.
	User name "john gallagher" not valid: invalid character: " ".

Quoting the arguments is valuable, especially when they are strings and on the end of a message. For example, the second message below makes it clear that the cause of the error is that there are trailing spaces in the URL:

	Invalid URL: http://www.foo.com   
	Invalid URL: "http://www.foo.com   "

The principle of being precise means that error messages should not be of the format “x or y occurred”, for example, “The database could not be connected to or there was an error during initialization.”

As a programmer, I can clairvoyantly read that code:

    try {
        db.connect();
        db.initialize();
    }
    catch (Exception e) {
        throw new DBException("The database could not be connected to or there was an error during initialization.");
    }

That’s just irrational laziness, leading to user frustration (and calls to support). The basic principle is: give the user the information to solve their own problem.