Writing good error messages

A good error message should say:

1. What the program was trying to do.
2. What it expected to have happen.
3. What actually happened.

This is the same requirements of a good bug report, except that there is no need to show the code used. And actually, the location of the code (source file and line number) should also be included in an error message unless it's completely obvious. This is such a common requirement, many systems include source location automatically:

$ perl -e 'die' Died at -e line 1.

The more difficult thing, surprisingly, is knowing what errors to report. Most system errors should be reported, but not if the code tries to work around the problem.