[buug] Best practices for stderr messages?

Karen Hogoboom khogoboom at gmail.com
Fri Dec 24 07:07:02 PST 2010


The program in question is a collection of shell scripts that I'm

> writing for social research analysis.  There will be some seasoned
> Unix/Linux users in the target audience but many will be Mac or Linux
> people unfamiliar with Unix conventions.  I expect that users will
> have a range of familiarity with the technique from novice to expert.
> So I have a particular interest in my error and warning messages being
> technically precise but also straightforward and intelligible, without
> being too verbose.  (One thing that I'm doing to help accomplish this
> is to provide references to published and unpublished articles that
> discuss the issue raised by the warning/error, e.g., (see: Rubinson
> 2009), which should help a bit.)
>

I like the idea of providing the links.  That's a good idea.

I provide different error messages for each error state if I can.

I try to tell the user what they can do to fix the error.  If not, I tell
them which input was not expected.  I tell the user which module it failed
in because I don't assume that they are the one who had the problem.  I.e.,
it could have been me the programmer, or some other programmer down the line
trying to maintain my stuff.  I make the message clear enough for other
programmers to maintain my stuff because I don't assume that whoever paid me
to write the software will necessarily want to be tied to me in perpetuity.
I decide I am a professional software engineer, not a future slimey
consultant.

I think it's better to use more words if it's going to save the user time in
fixing their problem.  I.e., they could spend more time reading the error
message and then know what to do, or they could read a few ambiguous words
and spend the rest of the day Googling.

I take the time to make it concice and clear.

I do not necessarily make the error messages complete sentences unless it
really takes more than one sentence to describe the problem and how to
recover from it.

Karen

http://www.linkedin.com/in/karenlhogoboom
http://www.facebook.com/klhogoboom
http://boomtownbits.livejournal.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://buug.org/pipermail/buug/attachments/20101224/11b01a25/attachment.html>


More information about the buug mailing list