Discuss naming conventions for traits

[dtolnay]

Go has one pretty clear convention for interfaces:

By convention, one-method interfaces are named by the method name plus an -er suffix or similar modification to construct an agent noun: Reader, Writer, Formatter, CloseNotifier etc.

In Rust we have some categories:

• Imperatives like io::Write, fmt::Debug, clone::Clone
• Agent nouns like iter::Iterator, hash::Hasher
• Nouns like fmt::Binary, ops::Fn
• Adjectives like marker::Sized, panic::UnwindSafe
• Preposition like convert::Into, borrow::ToOwned

Are there any conventions we can distill out of this or is it a free-for-all?

[alteous]

Imperatives should be preferred, especially for traits that perform tasks, since they clearly convey the intention. io::Read, clone::Clone, serde::Serialize, ops::Add are unambiguous. For marker traits it doesn't really matter.

Having said that it's disappointing that the standard library chose Iterator over Iterate or otherwise.

[brokenthorn]

"iterator" is a trait, while "iterate" is an action. Now why would you name a Rust trait according to an action (a method) when you're thinking about types and what a type is, when you're implementing a trait?

[ukd1]

Isn't iteratable clearer?

[drmason13]

Iterator is particularly weird because clearly you can iterate over a Vec, but Vec doesn't implement Iterator.

Also, the key method for Iterator is next() but who wants a trait called iter::Next? It would be consistent but it's just weird.

And also, to get an Iterator you can use IntoIterator's into_iter() but often you actually use a method of the type itself like slice::iter.

Perhaps the conclusion is that Iterator (noun agent) as a naming convention is the exception rather than the rule and it actually hints that the trait is more complicated than you might expect.

As an aside, almost every rust parsing library I've seen uses Parser for their trait name (I'd use Parse personally).
I guess the intuition there is that Parsers and Iterators are things that you get returned from functions and move around and use later. But then I don't know why we don't also have Writers and Readers.

I think effectively it is a free-for-all after all.

[Centril]

Personally, I think Iterator and adjectives / agent nouns is right because traits describe classes of types as well as constraints / properties on types. Therefore, I think imperatives should not be preferred.

[brokenthorn]

@Centril I agree. Iterator structures are structures that can iterate (over something). .iter() thus returns an iterator like the trait name implies. And even in plain English, you would say that the structure has the trait of an iterator (it is an iterator). You don't say the structure is an iterate (like @alteous suggested).

I'd say the naming convention should be "think in plain English".

Additionally you can observe that every other naming convention except Agent nouns have their trait's meaning logically linked to the module name. For example, you would think of the io::Write trait together with the module name, not apart. Write is an ambiguous trait by itself; io::Write though can be thought of as a "write IO" trait (or "read IO" and what have you). So when the trait name is ambiguous, you can probably read right to left and get a better sense of the trait: you would call a StdOut structure a "write IO" (as in, it has the qualities of a write IO, generically speaking).

convert::Into and borrow::ToOwned are just as easy to read. Any type implementing these traits, implement the traits of "into converting" and "ToOwned borrowing". fmt::Binary reads as the "binary formatted" trait.

The only exception? Agents. Agents like iter::Iterator though, don't read like that. In fact Iterator reads much cleaner, except it's good to know that the Iterator implied is one as defined in the context of iter:: and whatever iter:: is meant to provide.

[ghost]

My feeling is that our trait names have nothing to do with imperatives/nouns/adjectives/etc. Instead, trait names adhere to the following rules:

1. If the trait has a single self-explanatory method (or a set of nearly identical methods), name it after the method: Clone, Hash, Default, Into, Write, ToOwned, AsRef, Extend.

2. If the trait has no methods, name it after what ability (Send, Sync, Copy) or property (UnwindSafe) its implementors have.

3. If the trait has a broader set of methods or a single method that is not self-explanatory, the name should describe either what its implementors are (Iterator, Hasher, Fn, Error, Future, Termination) or what ability/property they have (AsciiExt, fmt::Debug, fmt::Binary).

[brokenthorn]

Hey @stjepang, your 1 and 2 points are basically the same idea so you could simplify and lump them together ("if the trait exposes mainly one primary method or property/ability, name it like that method or property..." followed by examples).

Regarding point 3, describing what implementors are, pertains to the previous classification of agent nouns but you add simple nouns in the mix as well (AsciiExt, fmt::Debug and so on) which you call as describing what property/ability an implementor has. I guess your point 3 is all about the nouns...

In my opinion you've only simplified the classifications a bit but it might detract from meaning which might impede understanding. I do think though that what should come out of this is a more formal explanation of the rules. The rules should be as simple as possible, but not simpler (to quote Einstein, hehe).

[ghost]

It might also be helpful to write down names of existing traits and fictional traits with slightly different names, then try to guess what would an implementor of each of those traits do. Here's a try...

Iteration over lists:

1. Iterate - can be iterated over
2. Iterator - iterates over something (*)
3. Iteration - is a single iteration or the result of one

Process termination:

1. Terminate - can be terminated
2. Terminator - terminates something
3. Termination - is the process of termination or the result of one (*)

Task execution:

1. Execute - can be executed
2. Executor - executes something (*)
3. Execution - is a single execution or the result of one

Writing bytes:

1. Write - can be written to (*)
2. Writer - can write to something

Value hashing:

1. Hash - can be hashed (*)
2. Hasher - can hash something (*)

Stack unwinding:

1. Unwind - can be unwound
2. Unwinder - can unwind something
3. Unwinding - the state or process of unwinding
4. UnwindSafe - is safe in the context of unwinding (*)

Sending values to other threads:

1. Send - can be sent (*)
2. Sender - can send something
3. SendSafe - is safe to send (same as 1.)

Unpinning values:

1. Unpin - can be unpinned (*)
2. Unpinner - can unpin something
3. UnpinSafe - is safe to unpin (same as 1.)

(*) traits that actually exist

[ukd1]

@ghost late reply here, but the most of the "can be" ones I find confusing as they feel like actions that could be taken (e.g. "send something"), or types (e.g. "Hash"). I think "sendable" makes it clearer that something "can be sent" - i.e. "...able" for traits.

e.g. using your examples:

• Unpin -> Unpinable - can be unpinned (*)
• Send -> Sendable - can be sent (*)
• Unwind -> Unwindable - can be unwound
• Hash -> Hashable - can be hashed (*)
• Write -> Writable - can be written to (*)
• Execute -> Executable - can be executed
• Terminate -> Terminatable - can be terminated
• Iterate -> Iteratable - can be iterated over

[StunxFS]

Exact! I think that's great!

[elpablete]

This reads really well, maybe I find it that way because English is not my first language. But this just reads way better than other examples in the discussion.

[WiSaGaN]

It may also be good to note there is an established convention of using "Ext" as part of an extension trait name.

Examples in std:
std::os::unix::fs::FileExt
std::os::windows::fs::FileExt
std::ascii::AsciiExt
std::os::unix::ffi::OsStrExt
std::os::windows::ffi::OsStrExt

[mmastrac]

Is there an established pattern for third-party crates adding extension traits? For example, we're working on modernizing rust-timers which currently has a FutureExt trait. This obviously conflicts with the futures-rs builtin extension, which means that users who want to get both extension traits have to jump through hoops and rename one of them:

use ...::FutureExt;
use ...::FutureExt as FutureExtFromTimers;

Any thoughts on a naming convention to avoid this conflict? Or alternatively, is it best to just accept the name conflict and punt it to API users?

Here's a pared down example: https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=e95429439d466dff254454f92851f845

[Nemo157]

@mmastrac that can be handled via unnamed imports

use futures::FutureExt as _;
use rust_timers::FutureExt as _;

(though that doesn't help with method name conflicts).