Program Eloquence Considered Harmful

Trying to minimize the error message as the implementor is a dangerous game because nobody else will have as much context as you. Rust error messages are widely lauded because they give context and help, not because they minimize character count.

My priorities for errors are:

- enough context to find the error and possibly further information

- consistent formatting so users can learn pattern recognition. Powershell is much better at this than Unix tools because the shell displays errors

- error message should fit on one screen and little but the relevant error should be printed after an interactive command

Terseness is mostly relevant for non-interactive use such as log files that need to be read quickly.

I generally agree with this, but making sure your error messages are correct is even more important than terseness. The last example of the article is a perfect illustration of this:

  $ cat invalid
  cat: invalid: invalid path

An invalid path or a file not found are not the same thing! The real danger is that being too terse and unclear is worse than unnecessary verbosity.

Re: cat

cat is just passing along the error string from the libc/system call it used. That error string is standard-ish over most libcs; some unixs can read directories as if they were files.

Changing that message would require significant additional complexity in cat which probably isn't useful.

Nitpick: eloquence and verbosity are two very different things.

> For one thing, repeating the entire search query in bold isn't necessary.

I hugely agree with the thrust of this article, but this Google example might be a mistake to include. It’s the only lay-person example here, not a shell or programming language for technical people. Showing a Google query back to a user, I might speculate, has an important function of allowing users to see spelling errors they didn’t know they typed. I can imagine other reasons as well, and I’d be willing to bet that Google has tried both and decided on repeating the output. The other thing not discussed is the Google output is organized hierarchically, separating the error from the tips, and bolding the search query. Those two things could dramatically improve the PowerShell output, for example, without removing any text. No other example had style formatting, and good styling and layout can be as effective as silence.

I like the approach that ShellCheck uses for its verbose error messages. Every error message is identified by an easily-googleable error ID that is not translated and there is a link to the shellcheck wiki where you can find an in-depth explanation of the error and possible ways to fix it.

For example, a typical run of shellcheck might look something like this:

    ~/test> shellcheck blah.sh

    In blah.sh line 2:
    echo $1
         ^-- SC2086: Double quote to prevent globbing and word splitting.
    
    Did you mean: 
    echo "$1"
 
    For more information:
      https://www.shellcheck.net/wiki/SC2086 -- Double quote to prevent globbing ...

https://github.com/koalaman/shellcheck/

This seems completely wrong to me from the user-end. When I need to debug a problem, the last thing I want is a three-word error message.

The author's arguments might work if there's some obvious place to go for more information. I'd take "invalid path: check ~/cat_error_log for more."

If people see a wall of text, they (from my observation) tend to skip it and conclude that the thing "just doesn't work". Even if the error is explained. So in that, they have a point. A little related are overly elaborate efforts to be cute and cheer up the user on error. (This of course happens more in Web GUI than in command line.) These can be infuriating and make one wish someone expended all this effort and money to actually make the thing work, instead of lecturing me not to get mad, with pictures.

But I think terseness is an imperfect proxy for clarity. In the Google search example, repeating the search query to the user may be actually useful. They may have pasted something by accident and/or heavily mistyped and not even have noticed. Do include important information, so the user can go directly to the place of fault. State what is wrong and try not to have the same message for many unrelated errors.

By the way, I'm still waiting for an "Unreasonable effectiveness of X considered harmful" article.

>And even in "normal" applications -- where the majority of users are not knowledgable enough to know that their spelling could be to blame -- an error message that's too verbose is still problematic, because many, if not most, non-techy users won't bother reading it!

Assuming users are 'too dumb' or 'smart enough' sounds like a broad generalization that's highly dependent on the tool.

I'm glad we have verbose compiler errors, and I write C++ for a living. Am I too smart for verbose output?

My grandmother can't login in to Facebook, should we forego the error dialogs because she's not going to read them?

I believe that terse error messages have their place, but this article over generalizes and is full of personal preference rather than data driven conclusions.

Strongly disagree on the SSH example. Security warnings should be a little more alarming than just "Continue yes/no".

Asking whether they are sure they want to continue has added context to make someone think twice about whether they are really connecting to the correct host.

Likewise, repeating the host address again after confirmation makes an error more likely to be spotted if it's off slightly (think along the lines of spaced repetition helping memorise things).

> Why? Because users don't like reading

One assumes an audience for the error message. Unix definitely assumes expertise. Windows assumes a neophyte. Given that something has gone wrong, the question is the shortest path to a remedy.

Disagree a bit on the Google example.

> For one thing, repeating the entire search query in bold isn't necessary. The user already knows what they searched for.

Echoing the input is useless. But if the program is interpreting the input somehow (like there are keywords or commands allowed), then showing the user what the program understood could be critical to finding the problem.

Hard disagree on that message.

The argument of "the user" is similar to that for "the web user" where web design is mostly about not making people think. You want them getting to what they want as fast as possible, so no reading, no extra activities, get them to their goal... because that usually means a transaction.

In this case, we should also get the user to their goal. Which is different from that of a web user. The goal here should be to give the "user", which is mostly going to be a developer or someone trying to perform an action, the best possible info on how to accomplish that action and what went wrong the time before that.

So that they can see what needs to change immediately and there should be no 2nd time with yet another error message.

The context is different, but both approaches are about best serving the user in their respective context.

A note on cat: on older Unixes (I remember it specifically in some old version of solaris), you can actually cat folders, and it will show a directory listing. Iirc in the orogonal unix, read() on a directory fd would just dump out some filesystem internal structs that detailed the folder's contents.

  g++ -fmax-errors=1

is usually enough. Sometimes you forget a brace and it's the last error. But sometimes you really need to paw through all those errors.

Controllable verbosity is best practice. Quiet defaults are nice though

I largely agree with the general point, but in the SSH example the “Continue?” is too terse, because it’s not entirely evident what “continuing” will do in that situation. “Connect anyway?” would be much better.

It would be great if there would be a way to interactively “expand” error messages on the command line, in the sense of progressive disclosure in GUIs. Meaning that you could for example have Help/Technical Details/Stacktrace buttons. Or you could interactively expand an error to -v or -vv verbosity level.

In logs this can be partially achieved by logging additional details with a low logging level. With errors coming from exceptions in particular, I like to log the error message (exception message) separately from the stack trace for that reason.

On the other hand, I try to run `brew update` and see nothing for 30+ seconds. I wonder if its hung up? Nope. There is absolutely no indication to the user what's happenning behind the scenes. I tried filing an issue and the brew maintainers closed it in record time without explanation. Verbosity helps when it's done right.

Error messages should be laconic.

I try put as much context as possible into my error messages, I serialize the request object too. I think this is because you shouldn't be debugging in production.

What I would love would be a change—aware stack trace, so when an error occurs, the most recently run, changed code is highlighted.

The article and programs make an assumption that I disagree with: That there is only one appropriate way to output error messages.

This is an absurdity. Both methods are valid. Different people want different things from the error messages.

This is most commonly addressed in programs using "verbose mode", often with multiple levels of verbosity ( -vv or -vvv ).

Another type of error message which I wish was a required standard is to output structured error messages in the form of JSON containing all the relevant bits of information. It is very annoying to have to parse apart error messages coming from a tool being called programatically.