Error messages will always include the name of the command that issued them. This is useful in identifying the source of errors when using EC, CRUN, etc.
Most messages will consist of the name of the command in upper case, followed by a colon, followed by the actual text of the message. For example,
SLIST: Unknown option '+opq'
Note that a good way of doing this is in a B program is with the expression
error("%s: message*n", uppercase(argv[0]) );
in the event that the command may be called with a number of different names.
The only exceptions to this format are so-called "usage" messages. These are used when a command line is found to be invalid for some reason. A "usage" message begins with the string "Usage:" and then gives an indication of the standard format of the command line. This should include all the options that may be specified for the command, as in
Usage: COPY infile outfile [Size=NN] [-Verbose] [-All]
"Usage" messages are only useful if the number of available options is small (i.e. if the sample command line can fit on a single line). If there are a large number of options, the command should not bother with a "usage" message, but should just print a standard diagnostic. Some standard messages are
CMD: %s is an unrecognized argument. CMD: %s is an unrecognized option. CMD: the %s argument is missing.
Note that there is no point in printing a usage message like
Usage: CMD file options
If it is not feasible to list the options specifically, don't bother with a "usage" message at all.
Programmers should note that error messages should not have an overly negative tone. This is especially important these days when computers are being used by people with little or no experience. Beginners are far more likely to be happy with a system that says
I'm confused by what you typed in
than with one that chides
BAD ARGUMENT
Machines are more thick-skinned than people; let them take the blame instead of shouting at the user. Error messages with a concise positive tone are pleasing even to the experienced programmer.
Copyright © 1996, Thinkage Ltd.