RFC: Resolve numerous naming conventions

[aturon]

This is a conventions RFC for settling a number of remaining naming conventions:

• Referring to types in method names
• Iterator type names
• Additional iterator method names
• Getter/setter APIs
• Associated types
• Trait naming
• Lint naming
• Suffix ordering
• Prelude traits

It also proposes to standardize on lower case error messages within the compiler
and standard library.

Rendered

[alexcrichton]

Show doesn't quite fit into this category because its method is called fmt due to sticking with the other formatting traits. (not sure if that affects this convention)

[aturon]

@alexcrichton nits addressed.

[aturon]

I am especially interested in feedback on the trait naming convention, which I think really affects the terse feel of Rust but which is still pretty vague.

[aturon]

Update: I've added two new sections after another round of API stabilization: additional iterator method names, and prelude traits.

cc @brson @huonw @alexcrichton @nikomatsakis

[aturon]

@arcto

Traits such as Copy Clone Show ToCStr each describes a specific capability. With this in mind Reader would be confusing if shortened to Read.

Yes, the convention would be maximally clear if it only applied to single-method/capability traits. However, I'd argue that for Reader the read method is the "primary" one in that everything else has a default implementation. (Though, by the same argument, Iterator should be Next, which is... very bad.)

I think you're probably right about Reader. So a general question would be: when is the -er suffix appropriate?

[arcto]

Would ReadStream be better than just Read? (just thinking aloud)

[arcto]

Iterator is the established name. The capability, in my mind, is GetNext. However, in getters the get_ part is omitted, so what's left is just next(). Not arguing for a specific trait name, though.

[Gankra]

This naming scheme can result in clashes if multiple containers are defined in the same module. Note that this is already the case with today's conventions. In most cases, this situation should be taken as an indication that a more refined module hierarchy is called for.

We're going to have to rework how we do re-exports in libcollections then. See e.g. btree

[alexcrichton]

I'm a little wary about the *-Prelude convention as we have so little experience with it so far, but I suspect that it will turn out alright.

[aturon]

@gankro

We're going to have to rework how we do re-exports in libcollections then. See e.g. btree

This is primarily due to the map and set being flattened into a single module, right? I think separating these out was a change we wanted to make anyway.

[aturon]

@alexcrichton

I'm a little wary about the *-Prelude convention as we have so little experience with it so far, but I suspect that it will turn out alright.

It should be the case that these name choices are totally irrelevant to the vast majority of Rust code. But maybe it's worth prototyping these changes to check that's actually the case.

[Gankra]

@aturon btree's map/set are separated out into separate modules, but the parent btree module re-exports things for convenience (same story for the hashmap/set modules).

[aturon]

@gankro Right. I think maybe we weren't on the same page about what the final state of these would look like. Personally, in the end, I'd prefer for e.g. btree's map and set to show up at the root level as completely independent modules.

[Gankra]

@aturon Would there still be a parent btree module in reality, with the modules just re-exported to the root of libcollections? Or would they both be root-level modules in the actual source tree?

[carllerche]

I don't see anything regarding builder style, which I enjoy:

For example, in my curl bindings:

http::handle()
  .get("http://www.example.com")
  .header("Authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
  .exec();

The thing about it is that the builder style usually just sets values on a builder struct, but doesn't follow the set_foo convention.

[reem]

Agree with @carllerche. The builder pattern is extremely useful and very flexible.

[aturon]

@carllerche @reem Oh, definitely! (There's a section on builders in the guidelines already).

I'll add a clarification that this new convention does not apply to builders.

It's worth thinking a bit about whether builders should expose getters as well (opinions vary) and if so, whether they just follow the reverse convention: foo to set, get_foo to get?

[aturon]

@carllerche @reem Pushed an update to clarify.

I think I'd like to handle builder conventions via a separate RFC -- in particular, I'd like to put the guidelines I wrote earlier through the RFC process. Right now it's mainly a description of how this played out for Command and TaskBuilder.

[Ericson2314]

Read / Write sound good to me. Maybe Iterator could become Iterate, though not sure where that leaves Iterable.

This is primarily due to the map and set being flattened into a single module, right? I think separating these out was a change we wanted to make anyway.

Quiet unrelated to the RFC, but it would be nice if the backing data structure and it's core functions were in a separate file from the, e.g., *Map and *Set public data structures and their many bland impls. I've multiple times gone to look at the collections implementations and found it annoying to wade through 1000+ lines trying to find the interesting bits.

[reem]

Read and Write makes me think that the type itself can be read or written, as in the case of something parseable and showable. Reader, Writer and Iterator are much clearer in this case.

[arcto]

Here's a nice naming convention for getters and setters, common in C++. But it requires function overloading:

fn name() -> &str;
fn name(s: &str);

This one is also compatible with builders.

[petrochenkov]

@arcto These "nice" getters and setters can't be distinguished with simple text search and aren't encouraged by popular style guides.

[aturon]

Note: I've pushed a minor update to the lint naming rules, reflecting my experience actually rolling out the conventions. Other than clarifying the existing rules, the main change is standardizing on "unused" (where we previously had "unnecessary", "unused" and "useless"). This matches the unused umbrella lint, as well.

[brendanzab]

What about [T, ..N]? array? fixed? In cgmath we use fixed.

Should tuples be considered as well? Or should we wait for those conventions to emerge naturally for now? (I haven't seen many tuple conversions yet).

[nikomatsakis]

I think the reason that Reader being called Read seems odd to me is that read() doesn't feel like the primary method of Reader to me -- there doesn't seem to be a "primary" method.

[alexcrichton]

Tracking: rust-lang/rust#18074

Discussion: https://github.com/rust-lang/meeting-minutes/blob/master/weekly-meetings/2014-10-14.md#naming-conventions