Spelling bikeshed: "implementor" or "implementer"?

Currently (6a10920), "implementer" is used 49 times in rust-lang/rust, compared to "implementor" which is used 274 times.

According to Google Ngrams, "implementer" is the more used spelling my a wide margin, both in American English (by a wider, accelerating margin ~ 20×) and in British English (by a smaller margin ~ 10×).

dictionary.com lists both forms with -er first, as does Merriam-Webster.

Cambridge Dictionary lists -er but not -or. The Firefox en-US spellcheck dictionary accepts implementer but not implementor.


Obviously the choice is fairly arbitrary; by any reasonable interpretation both forms are still accepted. I do think it makes sense to standardize the existing uses in rust-lang/rust onto a single spelling.

"implementor" could be chosen due to currently being the more used spelling in the repo.
"implementer" could be chosen due to being used more frequently, especially in AmEng which the rust project tends to prefer.

What do you think?

  • implementer
  • implementor
  • allow both

0 voters

1 Like

Given Ngrams alone, -er seems to be the most reasonable choice.

Neither is listed as "less common", "uncommon", or similar language, so they're actually co-equals (and likely just listed in alphabetical order).


Overall I'd love to have someone go through and fix typos and standardize to American English (which is what is officially preferred last I checked).

3 Likes

I have the impression that implementor is a hacker-ism; there are a few other words for which -or is more common in technical writing even though -er is more common in general English.

No objections to changing to the more common usage in this case.

9 Likes

Why do we have to, or why should we, pick one to use at the expense of the other?

Picking one and changing all existing usages to it strikes me as adding noise to the commit logs. Although, I admit that the numbers here are small enough that the downside here is probably close to nil. So doing that seems fine... But what doesn't seem that great is how we maintain that standard. Are we going to have automated tooling to check for banned usages? If so, that will at least not waste reviewer time and probably has a high likelihood of maintaining the standard. Maybe that would be fine? But without automated tooling checking for banned usages, this strikes me as more trouble than it's worth.

Personally, I don't think "consistency" is a good reason in this particular example. I grant it is a reason, but one with probably very small upside. The downside is that everyone writing docs needs to be aware of this rule.

If it's one rule on one particularly not too common word, then in practice, it probably won't waste too much time. But if this is the first step in a long list of banned words in the name of consistency, then I think I would be opposed to that.

Apologies if I took this in a different direction than what was intended here, but I'm just personally very skeptical of these sorts of rules.

EDIT: to be clear, I am okay with having official preferences. And maybe that's all that's being asked for here. In which case, I would say to just ignore this comment. :slight_smile: But with the caveat that those preferences don't get elevated to burning time during PR reviews.

9 Likes

Clarifying: I think this is a matter for style guides and occasional cleanups, not CI and tidy tools.

1 Like

I have to agree with burntsushi here.

Having a rule for these seems worth it for a particular book, but for the docs overall seems like more trouble than it's worth.

Mostly: this is a bit of a curiosity from me running into saying "implementers of a trait" immediately followed by a link to rustdoc's "Implementors" section. I'm very much a descriptivist rather than a prescriptivist, but I also definitely find examining grammatical subtleties interesting.

For internal documentation / comments / etc, I fully agree that it doesn't really matter. What matters about language is that the meaning is communicated with minimal loss of precision, and if that is met, the rest doesn't really matter[1].

But that said, the API documentation as a unit is (ideally) a cohesive whole the same way any book is. Consistent use of language helps in precision; inconsistent use of spelling may imply a different meaning between the spellings.

Rustdoc's "Implementors" section existing on every trait page probably means it's better to normalize to that.


I think I have my own little bit of grammatical differentiation between the spellings. While it is a loose association, I think I use/differentiate both spellings with slightly different definitions w.r.t. time:

  • Implementer: One who has implemented
  • Implementor: One who provides implementation

When spellcheck is yelling at me, I end up correcting to implementer consistently. When using both in close proximity to each other, I'll normalize to one or the other. But I think in a vacuum, I'd say that myrrlyn is the implementer of bitvec but myrrlyn is the implementor for bitvec. There's grammatical subtlety there that I (as an armchair linguist) am not capable of pinpointing exactly. (And it's the kind of thing where observing the behavior influences the behavior; to get a proper study you'd have to have legacy data to analyze, contextualize it to the time period, etc.)


  1. A really fun paraphrase along those lines: the english spelling reform comes when we stop correcting peoples' spelling. ↩︎

2 Likes

FWIW I've standardized TRPL on "implementor" precisely to match the "Implementors" section in the API docs. I have spellcheck in the book's CI and it has caught me spelling it the other way occasionally. Spellchecking code would be... tricky, though.

2 Likes

I haven't checked how it handles this specific case, but there is a crate that fors spell checking. It's meant for CI, so it minimizes false positives.

That's a good point.

I wonder if it'd make sense to just say "Types implementing this trait" for that header to avoid the question, and the potential -er/-or distinction.

Arguably there’s currently an inconsistency between the names of the sections

  • Implementations on Foreign Types
  • Implementors

anyway? I mean, not a bad one, but these sections could be more similarly named either as

  • Foreign Type Implementors
  • Implementors

or as

  • Implementations on Foreign Types
  • Implementations

Except that “Implementations” is currently also used for methods (and associated functions) on the trait object type, see e.g. Any in std::any - Rust.

I’m now seeing an inconsistency between the use of “Implementations” on the main page vs. “Methods” in the sidebar for the same section. That’s weird… It’s even weirder for traits, because they then have

  • Required Methods
  • Provided Methods
  • Methods

in the side-bar, where the first two are about trait methods (and associated function) and the last one is about methods (and associated functions) on the trait object type.


TL;DR, I think there’s room for improvement, and possibly the best solution would also drop the word “Implementors” anyway.

3 Likes

sorry, this is probably getting kind-of offtopic; we can move to a different thread, if anyone wants to discuss this further

Maybe just stick with the (slight) abuse of “Methods” for methods+associated-function, then “Implementations” is only used for “Trait Implementations” on documentation pages for types, and for “Implementations on …” on documentation pages for types.

The sections could then be renamed (and re-arranged) e.g. as

  • Implementations on Upstream Types
  • Implementations on Local Types
  • Blanket Implementations
  • Downstream Implementations

or

  • Implementations on Types in Dependencies
  • Implementations on Local Types
  • Blanket Implementations
  • Implementations in Reverse-Dependencies

or something like that; splitting up the “Implementors” further seems useful anyways: The current category “… on Foreign Types” is confusing anyways, as it’s not clear whether the foreign types are in upstream crates, or downstream crates, and blanket implementations apply to foreign types, too, anyways!

(Under blanked implementations, I would at least list impls on Self being a generic variable T, but also things like &T or Box<T> where the Self-type doesn’t cover the generic type variable. This categorization would also give more awareness to the fact that introducing such implementations is a breaking change, and that thinking about on such implementations when publishing a trait is important.)


Looking back at Any, the trait implementations for the trait object should probably get a new name, too, because “Trait Implementations” is confusing. Perhaps simply “Trait Implementations of dyn Any” (i.e. insert the name of the trait object) or “Trait Implementations of Trait Object” is better. Same for “Methods of dyn Any” instead of “Methods”, I guess.

2 Likes

The word “implementors” is also exposed in rustdoc URLs:

https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html#implementors

We can change the visible name of the section, but we probably don’t want to change the anchor. Is there any APIs or API-like usage of “implementers”?

8 Likes