Thinking about names, as well as scuba diving

There are 2 hard problems in computer science: cache invalidation, naming things, and off-by-1 errors.

Naming a project, tool, or concept that you want other people to use is a very hard problem. The most important thing, of course, is that the name sounds cool. Then, significantly less important, but still quite important, is that the name convey useful information to your users. This is where things get tricky. There are tons of different kinds of cool birds and sharks and reptiles we can name our projects after, but only some of those names also convey information to our users.

One of the best ways to name a thing you want people to use is for the name to convey some kind of accessible metaphor which can help people understand what this thing does, is for, or is about. At least, it will help if they are fluent in the language the metaphor is written in, which is probably English, because English dominates open source development. For example, “failure” is named “failure” because it is a project about error handling, errors arise when something “fails,” and more direct names were already taken. The metaphor can even be less direct: in Rust, code packages are called “crates,” a useful metaphor for boxing up all your code and shipping it to someone to use.

It’s important, though, that this terminology you use come from the user perspective, rather than from your perspective as the author. You should think about how the user will experience this thing you’ve made, rather than how you experience it as the creator. Failing to make this shift is an easy mistake to make.

Sometimes, you can’t come up with a handy, accessible, user-driven metaphor for your new thing. In this case, you will need to introduce some jargon that the user is going to have to learn. This is where scuba diving comes in.

A scuba is a tool used by divers to breath from when they descend deep under water. The term scuba is actually an acronym, short for “self-contained underwater breathing apparatus.” I would contend that the terminology scuba is much better than any abbreviation of that acronym which attempts to preserve meaning in its surface appearance. It is much more accessible to present to users the concept of a “scuba” as a new word to learn, than to present them a phrase containing terminology they may be familiar with, but which has developed specific, unfamiliar meaning in this context.

To give a concrete example, I think Rust’s use of the terminology “trait” was much preferable to the established terminology from Haskell: “type class.” Because its the conjunction of two words users are familiar with, they are likely to believe they can understand the meaning of this term analytically, by reconstructing its meaning from the meaning of its components. But the meaning of this terminology is specific, both because it uses the terminology “class” in a somewhat unusual way, and because it imposes its own new constraints on meaning as a conjoined term. “Trait” is much better, because users have less preconceived notions about what a trait is (unless they are coming from a language which has similarly adopted this terminology for their polymorphism, but those are relatively rare).

In contrast, I am personally unhappy with our choice to expose the user to the terminology of “proc macro” as heavily as we do, because it imposes on users the expectation that they will be able to analyze their understanding of the meaning of the terms “proc” and “macro” to generate a definition of proc macro. I think it would have possibly been better for us to develop new terminology here, even if it was some word users would have to learn the meaning of. But the “proc macro” terminology is already exposed on stable, so the ship has sailed.

I want this post to have a punchy conclusion - a hot take if you will - so this is it: names that are just made up out of nowhere are better than names that are constructed from internal jargon of the project domain, unless you expect all users to already be familiar with that jargon and that domain. For example, while a library about http could reasonably be called http, because you don’t expect to be teaching your users about http using that crate, if you intend to introduce users to the complexities of this subject through your project, its much better to come up with a random, flashy name for it that is at best vaguely related to the subject of it. This is what Niko did with chalk for example, and also what I did with the project I’ve been working on, shifgrethor (explaining what shifgrethor is comes later).