#how to errors

A little touch I've started to add to my command-line tools, inspired by docopt, is an "errors" section which is pretty clear to humans, and yet tells you precise API information. For example:

$ cdexec --help Execute a command in the given directory. If no command is given, just check if going into the directory works. Usage: cdexec [--] <directory> [<command> [<argument>]...] cdexec (--help | --version) [<ignored>]... Options: -h --help show this help text -V --version show version information Errors: need directory argument bad option: <option> error writing output: <...> error changing directory: <directory>: <...> error executing command: <command>: <...>

That describes every error this program can have, and those exact words will be the first thing written to standard error as part of the error message when those errors happen (prefixed only by "cdexec: ", since it is a universal convention for command-line programs to prefix their errors with the name they were invoked as).

This doesn't come up nearly as often as "docerr" for me, because most programs can reasonably just exit with success or failure and save all specificity for stderr, but I have a similar little touch for a program to document its exit statuses in help text.

For example, a diff program could use this section in its help text like this:

Exits:

    0 if the input files are the same

    1 if the input files differ

    2 if there was an error

And for ssh it would look like this:

Exits:

    0-255 exit status of the remote command

    255 if there was an error in ssh

My most important guiding principle for errors produced by code: look at what you know, and only put into the error everything the caller can't already know from how they called your code.

For example, you have a function which takes one file name, opens it, and does something with it. If the file-opening function gave you an error, then I would say the error from your function should look something like this:

opening file: <error>

Notice that

the file name is missing, because the caller knows the file name they passed into the call of your function that gave them this error,

but if your function took multiple file names, then you should include the file name, so the caller can tell which file caused the error,

the error from the underlying open call is included, because if you swallow that, then the caller can't know what happened, and

In principle I agree. In practice, it often means this boilerplate is between every line of the big-picture intended-behavior code - a serious worsening to readability, not to mention the experience of writing and editing the code:

if err != nil {

    // usually wrap+annotate error

    return err

}

Libraries, languages, and ecosystems need to represent errors in ways that don't lose structure.

It would be nice to also preserve full type information as long as possible, for anything that can use it. Within a programming language, this is often doable: error structures can remain native types, with all the richness of the type system, until they need to be serialized. But once serialized, you have to make choices about what types, if any, get first-class representations.

So the minimal universal interface is anything that can represent strings of human-readable text, lists, and maps. In languages and libraries, this means that the minimum API for errors should be:

is this a list of separate pieces of information? if so, then give me each of them.

is this a map of separate pieces of information? if so then give me the key and value of each of them.

so then this is a single piece of information: give me the string of it.

Real world errors in almost any nontrivial program are often inherently lists or maps of information. Errors from multiple retries or parallel operations. Errors gathering relevant information as they bubble up the call stack.

It is not enough for error information to be put in opaque forms like strings, because when the error has made it all the way up to wherever it is being handled or analyzed, we often need to be able to pull out those individual pieces, and you shouldn't need to know all formats and encodings that got mixed into the error string by every single API down the call stack.

In Plan 9, one insight was to make all errors strings - system calls return error strings, not error numbers that map to strings; programs return with exit strings, not exit status integers.

In Go, one insight was to allow any type to be an error so long as it can be turned into an error string. This allows errors to not throw away type information or smudge fields together into one string until it's time to output them as an error, giving code a lot more opportunity to easily and simply programmatically handle errors.

(Notice that these are part of the same design heritage. At least one of the UNIX guys went on to work on Plan 9 and then went on to work on Go.)

A living list as I figure it out. An ideal error in a programming language:

tells you what the problem was,

tells you what you can't already know,

names and lets you easily get any separate piece of information about the error,

lets you add separate pieces of information that your caller can't already know,

does not let you accidentally miss it,

does let you decide how to handle it - suppress it, modify it, or just propagate it,

does not let you do anything your caller has good reason to not give you privileges for,

can be replaced or wrapped with an error that says what the bigger picture problem was,

can be composed into a list of errors, to indicate that there were multiple errors,

keeps error code paths as free as possible of operations and allocations that can fail, and

is compatible with code paths for handling similar errors, but at the same time