Literal Names Policy (i.e. how to name packages)

Show and Tell
1

I have been using a “literal names policy” for naming everything I make in Elm. The result is:

This kind review reminded me that I haven’t talked about this policy in a while!

I wrote about it here because my goal is that the whole Elm community would use this policy as well.

Policy

When I create a package, I ask “What is this package for?” and the answer to that question is the name of the package. If I do not know what it is for, something has gone very wrong if I think it’s worth having other people review and possibly use this code!

This means we get elm-lang/html, evancz/elm-parser, rtfeldman/elm-css, etc. You can immediately know what it’s for. No cute branding to sift through. The only real distinguishing feature of the name is the author. This is extremely important information! You are implicitly collaborating with the author, and it is important to trust their quality, stability, communication, etc.

Ideal Scenario

Say you want to work with X. Which package for X is the best? The options should be:

alice/elm-X
bob/elm-X
chuck/elm-X

Rather than choosing the one with the best branding (like in JS often) you choose the author you trust most. Best track record. Best working relationship. Etc.

Playfulness

I think playfulness is definitely valuable in making engaging and fun packages, and a “literal names policy” means you cannot express that in the name itself. I think it is overall better if you express yourself in this way in the docs and examples. Make it fun to learn and use the package!

E.g. Renaming virtual-dom to domino and having a fancy logo would provide some people with some instant gratification. “Wow, a neat pun!” You don’t have to think about anything too hard to appreciate it. But is the library actually any good?! The “clever” name distracts from the fact that you must review the API and docs to have any useful opinion about the package.

In other words, use playfulness to teach the library, not to distract from the technical content.

29 Likes
2

I agree whole heartedly with this policy, but assume it’s quite a different deal to enforce than semantic versioning. Still, I hope that this posts both keeps people from using non-descriptive names in the future and maybe even convinces some people to rebrand.

P.S. I think you meant evancz/url-parser and not evancz/elm-parser? :slight_smile:

1 Like
3

Literal naming is very helpful when searching package.elm-lang.org.

Do you think package names should generally begin with ‘elm-’? I find myself putting elm- in front of my package names but also feel like it is redundant, since they are only going to run on Elm! It is a bit like calling C libraries c-printf, c-stdio, but seems to be a convention that has taken hold. Perhaps it doesn’t matter, as long as the rest of the package name is literal, it will be easier to find.

3 Likes
4

I think that for the elm-package server it is redundant, but helps with places like GitHub where the very literal names don’t really provide sufficient context.

2 Likes
5

I must say, I choose based on the exposed API. Package by my favorite author might not support the kind of stuff I need to do. If that’s the case and less-trusted author’s package supports the API, I choose it.

2 Likes
6

But you probably start looking at the package by the author you recognize and trust the most though, right? Or do you just go top to bottom, reading the APIs?

7

I think this is a huge deal for new users who are making the transition from getting started to building a first project. I recently picked up PureScript, and the packages I ended up using in my project were the ones that I could find in the search based on the vocabulary I had learned at that point. I wrote my own XMLHttpRequest wrapper, though, because “Affjax” is not a word. Affjax is a really nice package but I couldn’t find it when I needed it.

4 Likes
8

Right now, if I saw this, I’d assume these were 3 forks of the same library, rather than 3 distinct libraries for the same task. I’m not necessarily opposed to the policy, but it does run against both my intuition and lived experiences with OSS.

I also remember the two different libtorrents causing a major headache for both distro packagers and people compiling from scratch; but Elm is not likely to have its packages repacked by a distro or suchlike.

3 Likes
9

I start with that one, but if it doesn’t support the API, I go for another package.

10

I agree with this counterpoint. Especially with no way to privately publish packages, some users/organizations may fork + republish packages with no intent to maintain them. This policy would benefit from some additional package labeling that I saw discussed on GitHub (e.g. labeling a package as ‘unsupported’).

1 Like
11

I like the philosophy that Evan is encouraging here as it can result in a clearer and more self-documenting set of packages. In my first major Elm package I went through a process of initially giving it a cute name (Eve) and after feedback and noting Evan’s philosophy, ended up with the more mundane, but clearer elm-vega. In this case the ‘elm’ bit is not redundant in that it is explicitly a bridge between Elm and Vega rather than an alternative implementation of Vega.

I do wonder though if this approach might be storing up problems for the future as community packages proliferate. A group that share the same name but have different authors can be a mixture of forks with major or minor amendments, of alternative approaches and homographs. If I don’t know all authors, do I chose the one with the most recent edit, with the most active history, the most github stars, the oldest? Or do I deeply brows the API and source to make the judgement? Perhaps we need some form of crowd rating or even review repository that doesn’t rely on github?

(I realise none of the above is a consequence of Evan’s naming policy, but I think the problems are related to those that the naming policy is trying to address).

12

Yes, so such a collection of packages is discouraged from ever being brought in to existence. People will collaborate on mature packages rather that doing their own thing. Also, I’m grateful to the individual who forked and published one of my packages for saying that it was a fork, with a link upstream, at the top of the README.

I want to make a point of just how absurd naming is in some other language communities. “Circe” calls itself a “JSON library for Scala powered by Cats”. Apparently Cats is “a playful shortening of the word category”. Circe is a fork of Argonaut, whose naming rationale I can’t find but “Circe was a goddess of magic in Greek mythology, and had a role in purifying the Argonauts”. To find any of these, you have to prefix your google query with “scala”, essentially co-opting the “elm-whatever” pattern.

Then there’s the matter that Circe’s own documentation prominently provides no fewer than three pronunciations: “SUR-see, or KEER-kee in classical Greek, or CHEER-chay in Ecclesiastical Latin”. Whenever someone new wants to learn about this library, they have to spend precious time and mental capacity learning about this irrelevant detail and not a meaningful reason to use or avoid the library. Weird pronunciation and non-words pose a further barrier developers who are not native English speakers, or communicate through screen readers or sign interpreters. I have literally been in a standup where another developer interrupted to clarify for the interpreter that what some of us pronounced “lean” and others pronounced “line” was in fact the same tool. Said tool is named after a character in an irrelevant short story, that is quoted at the top of the README, daring you to waste an hour of company time.

Utter madness.

5 Likes
13

Hi. I have a couple of concerns with this policy.

Memorable names

If someone asks me what package they recommend for x in Elm in a conversation (in person or via chat) I have a hard time naming it without having to search for the package in http://package.elm-lang.org/

For me the author name is a very hard to remember distinction e.g.

jamesmacaulay/elm-graphql
ghivert/elm-graphql

I know which one we use and like, but I’ll never remember that name without looking it up.

In Ruby, JS, etc I can tell people straighaway as names are usually easy to remember.

Packages using the same module name

If a couple of packages have the same name, is likely that they will try to export the same module name. This is a problem right now https://github.com/elm-lang/elm-compiler/issues/1625. For now is difficult to migrate from one lib to another if they happen to use the same module name, as they will conflict.

If there is a way to rename modules in the future this point is irrelevant.

9 Likes
14

I have mixed feelings about the literal naming policy, and I agree with @Sebastian. It is really nice to be able to search for a package based on its functionality, but it makes it complicated to try and find a specific package. It’s confusing and difficult to find the version of Elm WebGL that is the correct, up-to-date version, winding a path through a deprecated elm-community package, to a specific author’s version of that package, back to the up-to-date elm-community version.

I mean… Elm isn’t called “delightful language for reliable webapps”. That’s its description. It can be handy to have some marketing and presentation.

4 Likes
15

At first I agreed with your counter-point but then I realized if I saw those 3 packages and assumed they were Forks of the same Library, the first thing I’d do is check each one to see how/if they differed in terms of their API or functionality. Rather than choosing the one with the most clever name.

…which basically just proved Evan’s point :smile:

4 Likes
16

It’s very common for people’s usernames to be locale specific and not mnemonic; it’s often a name plus an initial, i.e., a random letter, and the names may be hard to read or even unreadable for people from different locales; it also isn’t helped by separators being usually omitted from names. The ‘cutesy’ names that this policy is supposed to replace at least are usually meant to be mnemonic for English speakers, and the examples of “alice/bob/chuck” misrepresent the reality that most usernames are more similar to “zxcvbn”.

The result of this policy is that I don’t remember package names; I either need to look up their names in elm-package.json, or look through multiple similar packages and possibly still be unsure.

Edit: the ‘clever’ names also serve to signal that effort has gone into the package, while a yet another username/elm-X package just blends in with the others, many of which won’t have seen serious effort or maintenance.

2 Likes
17

Another significant negative aspect of usernames in package names is that usernames are not permanently fixed; usernames can be changed or the user accounts deleted. This naming system is setting Elm up for a leftpad moment. Just recently Go got burned because of this exact same thing, where someone deleted their GitHub account and broke a large number of Go dependencies.

Usernames being part of package names means that Elm package authors are stuck with their username, even though there can be many legitimate reasons to want to change it. Even people’s actual legal names change.

This is all on top of the naming conflicts, since the namespaced names are only used for installation, but importing modules doesn’t use the namespaces. It’s been pointed out already that the literal naming policy makes naming conflicts much more likely.

npm does it right where you can have user- or org-scoped or packages where it makes sense, and there can’t be conflicts.

2 Likes
18

As a concrete illustration, I can’t remember the actual names of the few elm-graphql alternatives relevant to me. I thought that the one that didn’t support Elm 0.18 but whose design I was interested in had a relatively short and anglophone sounding person name with an initial letter. I won’t single it out here, but turns out it was a compound of an anglophone first and last name, but instead of an initial letter, it was using the first few letters of the first name, and the last name was somewhat uncommon. The result was that the name is worse than not mnemonic; it’s acively confusing, since it looks like a ‘garbled’ version of a more common name. “zxcvbn” at least is somewhat clearly identifiable as random letters.

It doesn’t help that I’m from a non-anglophone culture, so I’m not really ‘wired’ as well for remembering or parsing anglophone names, like remembering whether something is spelled “Mc” or “Mac”, or differentiating similar names, etc. Anglophone names are just one kind of foreign name as well; for example, Central European language names tend to be difficult to spell and read as well.

There are plenty of difficulties with foreign or unusual names just within the context of Western culture, but the problems are multiplied when considering people from non-Western cultures; Asian cultures, for example. Given that most Elm users currently seem to be Western, this naming policy ends up being very Western-centric.

The bottom line is that the names being dismissively referred to as ‘cutesy’ are typically better suited for international audiences and inherently more mnemonic than usernames. Usernames are commonly not even chosen with any personal branding in mind but just for logging into an account, and usernames are often very locale-specific, unlike how package names are typically chosen. For example, the single Elm GraphQL package whose name I’ve had no difficulties to remember has been Graphqelm, and it’s now apparently slated to be renamed to [username]/elm-graphql. A simple word play on Graphql and Elm is an obvious memory aid and doesn’t really depend on a specific cultural background while being fairly literal; meanwhile, the username in question is the opposite in both aspects of mnemonic value and locale specificity.

There’s some aesthetic appeal in all packages being named after a uniform descriptive scheme, and the more creative names can sometimes be too figurative, but this naming policy is very arguably a case of throwing the baby out with the bathwater.

3 Likes
19

In the npm ecosystem, my observation is that:

  • There’s a huge preference for non-scoped package names, and a land grab for obvious ones. Whether or not this is by design, it’s what happens in practice.
  • Popular packages end up with names that have no relation to what they do - e.g. axios (HTTP), jest (testing), aphrodite (CSS).
  • These names must be memorized by everyone who wants to have a conversation about the ecosystem.

I would rather memorize “Dillon’s elm-graphql” than “Giraffe.js” for several reasons - one of the most important being that I’m learning something about a person, a community member, and not an arbitrarily chosen package identifier.

This is especially true for names I’m not used to seeing. The names Tereza, Abadi, and Ilias were not already known to me before I encountered them in the Elm community, and seeing their names in conversations about packages they’ve made helped me learn them.

I get that for non-anglophones, English names are harder to remember than familiar names. But given that both the Elm way and the npm way inevitably require memorization, I think it’s more worthwhile to learn the names (or usernames - I totally understand wanting to decouple legal name from username) of the people in our community than the arbitrarily-chosen names of branded packages.

9 Likes
20

There’s a large middle ground between [random animal name].js and every Elm GraphQL package being named elm-graphql; Graphqelm being an example of a name that is both as descriptive as elm-graphql but also unique and mnemonic. Human language is flexible enough that there are an astronomical number of ways to name any given library in a descriptive way, and a library being called “axios” instead of something like “yet-another-http-client.js” is more a stylistic choice than anything. The idea that npm’s public namespace would be close to running out of viable descriptive names for packages is on its face untrue and based on cherry-picked examples. The ‘obvious’ names being taken is not a significant factor, because there are so many possible alternative lexical combinations.

It’s just a false dichotomy between random package names and an uniform naming scheme. There can be a descriptive naming policy without requiring uniform names.

The stated benefit of usernames is putting the focus on the authors, but that is a moot point, because usernames are not fixed, and treating them as fixed means not learning from the npm leftpad fiasco. Usernames and even user account change; this is a central issue that hasn’t been addressed.

npm isn’t perfect, but it gets it right in the sense that a regular user doesn’t need workarounds like mirroring or committing dependencies to guarantee dependencies not breaking. Larger orgs run their own mirrors, but for most people it’s good enough to rely on npm’s central repo. Ditto for crates.io; a central repo with immutable packages is a best practice, while coupling packages to specific users or usernames has prominently failed. A more recent example than leftpad is the GitHub user hosting Go’s go-bindata package being deleted.

If the idea is to optimize Elm’s package system for the scale of npm, leftpad should be an important lesson, but an another more significant problem npm still faces is ‘typosquatting’ by malicious packages. Using usernames as part of the package name significantly amplifies the typosquatting problem, since usernames are often difficult to spell.

3 Likes