💾 Archived View for flexibeast.space › gemlog › 2022-06-23.gmi captured on 2024-02-05 at 09:44:28. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Error messages

There are so many dire error messages produced by software. A classic joke in this regard references Ken Thompson[a], one of the creators of Unix, as well as the creator of the programming language ‘B’ (the predecessor to ‘C’) and the video game ‘Space Travel’:

Ken Thompson has an automobile which he helped design. Unlike most automobiles, it has neither speedometer, nor gas gauge, nor any of the other numerous idiot lights which plague the modern driver. Rather, if the driver makes a mistake, a giant “?” lights up in the center of the dashboard. “The experienced driver,” says Thompson, “will usually know what’s wrong.”[b]

-- https://news.ycombinator.com/item?id=7727206

Recently a Rust dev, new to (Doom) Emacs, reported getting the error:

eldoc error: (user-error No such directory: /usr/local/src/rust/src. Please set 'racer-rust-src-path' or 'RUST_SRC_PATH'.

and asked "Why am I seeing this error, and how can I solve it?"

i couldn't really comprehend how a dev, even a new dev, could ask these questions. Even given the dev being understandably unaware of what ‘eldoc’ is[c], doesn't the error message make it explicit what the problem is, and what needs to be done to fix it? Something was looking for the directory ‘/usr/local/src/rust/src/’, but that directory doesn't exist. So either the ‘racer-rust-src-path’ variable (in Emacs) needs to be set, or the ‘RUST_SRC_PATH’ environment variable needs to be set. How does the error message not convey this?

It would've totally made sense to me if the dev had instead asked one or more of:

“What's ‘eldoc’?”
“Why is this ‘eldoc’ thing looking for that directory?”
“How do I set ‘racer-rust-src-path’ and/or ‘RUST_SRC_PATH’?”
“What value do I need to set one of those things to?”

But no, the dev was apparently treating the error message provided by Emacs like it's an inscrutable Guru Meditation[d] providing no actionable information.

i'm an advocate of trying to make error messages as helpful to the dev or user as possible. It's both sad and irritating that i _still_ have to occasionally resort to e.g. using strace(1) to examine a program's calls of open(2) because that program has failed with the error message:

Couldn't open file

For crying out loud, if your code tries to open a file, and it fails, don't just report to the dev or user that a file couldn't be opened! Describe _which_ file couldn't be opened, and pass on any information provided by the relevant system call regarding the reason for the failure, e.g.:

Couldn't open /some/config/file: Permission denied

That said, surely there's a point at which one can say: “I've provided the dev/user with all the information they need to fix the issue, but they seem to be ignoring it; more work here has an opportunity cost I'm not willing to pay”?[e]

☙

🏷 dev,ict

Glossary

Gemlog Home

☙

[a] Wikipedia: ‘Ken Thompson’

[b] This is a reference to ed(1), the text editor that Ken Thompson developed for Unix: ed's approach to error reporting is to simply print “?” (and nothing else). The glibc library includes an error macro ‘ED’:

“?.” The experienced user will know what is wrong.

“The GNU C Library” / “Error codes” / “ED”

[c] It's an Emacs system for showing the documentation for a particular identifier (e.g. a function) in Emacs' echo area.

[d] Wikipedia: ‘Guru Meditation’

[e] Having moved to Gentoo in the last year, i've been impressed by both the quality of error messages provided by e.g. emerge(1), and by how many users seek help with fixing an issue when the system has _literally told them exactly what they need to do_.