How detailed should error messages be?

Question

I was wondering what the general consensus on error messages was. How detailed should they be?

I've worked on projects where there was a different error message for entering a number that was too big, too small, had a decimal, was a string, etc. That was quite nice for the user as they knew exactly where things went wrong, but the error handling code started to rival the actual business logic in size, and started to develop some of its own bugs.

On the other side I've worked on a project where you'd get very generic errors such as

COMPILE FAILED REASON 3

Which needless to say was almost entirely useless as reason 3 turned out to mean a link error.

So where is the middle ground? How do I know if I've added descriptive enough error messages? How do I know if the user will be able to understand where they've gone wrong?

Answer 1

There are two possible target audiences for an error message, the user, and the developer.

One should generally have the message target the user.

o what is the cause of the problem.
o why the program can't work around the problem
o what the user can do to work around the problem.
o how to report the problem.

If the problem is to be reported, the report should include as much program context information as possible.

o module name
o function name
o line number
o variables of interest in the general area of the problem
o maybe even a core dump.

Target the correct audience.

Answer 2

You should communicate what happened, and what the user's options are, in as few words as possible. The longer the error message is, the less likely the user is to read it. By the same token, short error messages are cryptic and useless. There's a sweet spot in terms of length, and it's different for every situation.

Too short:

Invalid input.

Too long:

Please enter a correctly formatted IP address, such as 192.168.0.1. An IP address is a number used to identify your computer on a network.

Just right:

Please enter a valid IP address.

As far as code bloat is concerned, if a little extra code will prevent a user from calling support or getting frustraited, then it's a good investment.