RFC: Finalizing more naming conventions #430

Closed
wants to merge 1 commit into
from

Conversation

Projects
None yet
@aturon
Member

aturon commented Nov 3, 2014

This conventions RFC tweaks and finalizes a few long-running de facto
conventions, including capitalization/underscores, and the role of the unwrap method.

See this RFC for a competing proposal for unwrap.

Rendered

@aturon aturon referenced this pull request in rust-lang/rust Nov 3, 2014

Merged

refactor libcollections as part of collection reform #18519

+| General constructors | `new` or `new_with_more_details` |
+| Conversion constructors | `from_some_other_type` |
+| Local variables | `snake_case` |
+| Static variables | `SCREAMING_SNAKE_CASE` |

This comment has been minimized.

@alexcrichton

alexcrichton Nov 3, 2014

Member

Constants as well, right?

@alexcrichton

alexcrichton Nov 3, 2014

Member

Constants as well, right?

This comment has been minimized.

@reem

reem Nov 4, 2014

I think we should consider CamelCase for constants, since SCREAMING_SNAKE_CASE is extremely abrasive to look at and it more clearly demonstrates the difference.

@reem

reem Nov 4, 2014

I think we should consider CamelCase for constants, since SCREAMING_SNAKE_CASE is extremely abrasive to look at and it more clearly demonstrates the difference.

This comment has been minimized.

@alexcrichton

alexcrichton Nov 4, 2014

Member

Note that there are precedents in both directions here, and I'm not sure it's clear that we should draw a distinction between these two kinds of variables.

Looking around, we've got:

I'll also point out that "SCREAMING_SNAKE_CASE" is abrasive probably because it has the word "screaming" in all caps. Something like MAX_WIDTH vs MaxWidth seems less abrasive to me

@alexcrichton

alexcrichton Nov 4, 2014

Member

Note that there are precedents in both directions here, and I'm not sure it's clear that we should draw a distinction between these two kinds of variables.

Looking around, we've got:

I'll also point out that "SCREAMING_SNAKE_CASE" is abrasive probably because it has the word "screaming" in all caps. Something like MAX_WIDTH vs MaxWidth seems less abrasive to me

This comment has been minimized.

@utkarshkukreti

utkarshkukreti Nov 21, 2014

I was going to use enums to represent keys in a termbox-like console input library, but it turns out that Ctrl-I and Tab keys map to the same escape sequence so I'll have to use CTRL_I and TAB instead of CtrlI and Tab now if I want to use it in a match :(

@utkarshkukreti

utkarshkukreti Nov 21, 2014

I was going to use enums to represent keys in a termbox-like console input library, but it turns out that Ctrl-I and Tab keys map to the same escape sequence so I'll have to use CTRL_I and TAB instead of CtrlI and Tab now if I want to use it in a match :(

+
+| Item | Convention |
+| ---- | ---------- |
+| Crates | `snake_case` (but prefer single word) |

This comment has been minimized.

@alexcrichton

alexcrichton Nov 3, 2014

Member

In the past we've discussed how "foo-bar" is somewhat more aesthetically pleasing than "foo_bar" when looking at package names. I do think that this convention will have large ramifications on the contents of crates.io and cargo in general, so just wanna make sure we're sure about this!

If we go with snake_case, then we probably want to remove the quotes around extern crate "foo" as bar as they kinda only exist today to allow dashes.

@alexcrichton

alexcrichton Nov 3, 2014

Member

In the past we've discussed how "foo-bar" is somewhat more aesthetically pleasing than "foo_bar" when looking at package names. I do think that this convention will have large ramifications on the contents of crates.io and cargo in general, so just wanna make sure we're sure about this!

If we go with snake_case, then we probably want to remove the quotes around extern crate "foo" as bar as they kinda only exist today to allow dashes.

This comment has been minimized.

@huonw

huonw Nov 3, 2014

Member

We could make them optional, that is, extern crate foo as bar and extern crate "foo" as bar. (If we remove support for strings, then we essentially require that crates have valid identifiers as names, and so should probably have the compiler enforce this?)

@huonw

huonw Nov 3, 2014

Member

We could make them optional, that is, extern crate foo as bar and extern crate "foo" as bar. (If we remove support for strings, then we essentially require that crates have valid identifiers as names, and so should probably have the compiler enforce this?)

This comment has been minimized.

@reem

reem Nov 3, 2014

I personally prefer crate-name and then importing as a shorter name for crates that must be multiple words, though single words is strongly preferable. I think this works because they will usually be imported as a single word, i.e. extern crate "replace-map" as rmap; // from iron which is much nicer at the usage site than something like raw_trait_object::vtable(..).

@reem

reem Nov 3, 2014

I personally prefer crate-name and then importing as a shorter name for crates that must be multiple words, though single words is strongly preferable. I think this works because they will usually be imported as a single word, i.e. extern crate "replace-map" as rmap; // from iron which is much nicer at the usage site than something like raw_trait_object::vtable(..).

+
+### Fine points
+
+In `CamelCase`, acronyms count as one word: use `Uuid` rather than `UUID`.

This comment has been minimized.

@tshepang

tshepang Nov 3, 2014

Contributor

That looks not pretty... I prefer UUID. Why/when was this decided?

@tshepang

tshepang Nov 3, 2014

Contributor

That looks not pretty... I prefer UUID. Why/when was this decided?

This comment has been minimized.

This comment has been minimized.

@tshepang

tshepang Nov 3, 2014

Contributor

After going through the thread, I'm glad they went with Uuid. Thanks for the links.

@tshepang

tshepang Nov 3, 2014

Contributor

After going through the thread, I'm glad they went with Uuid. Thanks for the links.

@glaebhoerl

This comment has been minimized.

Show comment
Hide comment
@glaebhoerl

glaebhoerl Nov 3, 2014

Contributor

I think consts (as opposed to statics) should be CamelCase. Two reasons: lines up with enum variants, which they are semantically most similar to, and we can say that CamelCase is for "compile-time (known) things" (which types and constants both fall under).

Contributor

glaebhoerl commented Nov 3, 2014

I think consts (as opposed to statics) should be CamelCase. Two reasons: lines up with enum variants, which they are semantically most similar to, and we can say that CamelCase is for "compile-time (known) things" (which types and constants both fall under).

@brendanzab

This comment has been minimized.

Show comment
Hide comment
@brendanzab

brendanzab Nov 3, 2014

Member

Yup. I agree with @glaebhoerl on this. Either that or make variants screaming, but I don't think anyone wants that!

Member

brendanzab commented Nov 3, 2014

Yup. I agree with @glaebhoerl on this. Either that or make variants screaming, but I don't think anyone wants that!

@arcto

This comment has been minimized.

Show comment
Hide comment
@arcto

arcto Nov 3, 2014

I agree with @glaebhoerl in that constants and enum variants should share the same CamelCase. After all, enum variants are a kind of constant.

I think it's fair though that static variables stand out (using SCREAMING_SNAKE_CASE). They are a different beast -- especially mutable ones.

arcto commented Nov 3, 2014

I agree with @glaebhoerl in that constants and enum variants should share the same CamelCase. After all, enum variants are a kind of constant.

I think it's fair though that static variables stand out (using SCREAMING_SNAKE_CASE). They are a different beast -- especially mutable ones.

@glaebhoerl

This comment has been minimized.

Show comment
Hide comment
@glaebhoerl

glaebhoerl Nov 3, 2014

Contributor

That's the other idea I was going to float... perhaps it might make sense to distinguish mutable statics from immutable ones. Meaning that: we use normal snake_case for statically allocated immutable data (which is totally harmless), just like lets, and SCREAMING_SNAKE_CASE for both static muts and plain statics with any kind of interior mutability ("global mutable state, oh my!").

Contributor

glaebhoerl commented Nov 3, 2014

That's the other idea I was going to float... perhaps it might make sense to distinguish mutable statics from immutable ones. Meaning that: we use normal snake_case for statically allocated immutable data (which is totally harmless), just like lets, and SCREAMING_SNAKE_CASE for both static muts and plain statics with any kind of interior mutability ("global mutable state, oh my!").

@brson

This comment has been minimized.

Show comment
Hide comment
@brson

brson Nov 3, 2014

Contributor

This discusses acronyms in camel case but not snake case: e.g. is_XID_Start should probably be is_xid_start.

Contributor

brson commented Nov 3, 2014

This discusses acronyms in camel case but not snake case: e.g. is_XID_Start should probably be is_xid_start.

@netvl

This comment has been minimized.

Show comment
Hide comment
@netvl

netvl Nov 5, 2014

Especially big +1 for unwrap()/into_inner() convention. I think it is much better than renaming unwrap() on Option/Result.

netvl commented Nov 5, 2014

Especially big +1 for unwrap()/into_inner() convention. I think it is much better than renaming unwrap() on Option/Result.

@thepowersgang

This comment has been minimized.

Show comment
Hide comment
@thepowersgang

thepowersgang Nov 18, 2014

Contributor

Just to leave my two cents on the topic of statics. I'm all for "screaming case" (Caps) for constants, but for interior mutable data (StaticMutex) using snake case would be preferable. [Similar to @glaebhoerl's comment]

Contributor

thepowersgang commented Nov 18, 2014

Just to leave my two cents on the topic of statics. I'm all for "screaming case" (Caps) for constants, but for interior mutable data (StaticMutex) using snake case would be preferable. [Similar to @glaebhoerl's comment]

@glaebhoerl

This comment has been minimized.

Show comment
Hide comment
@glaebhoerl

glaebhoerl Nov 18, 2014

Contributor

(That's actually the reverse of my comment.)

Contributor

glaebhoerl commented Nov 18, 2014

(That's actually the reverse of my comment.)

@nikomatsakis

This comment has been minimized.

Show comment
Hide comment
@nikomatsakis

nikomatsakis Nov 18, 2014

Contributor

Isn't the convention not new_with_more_details but rather with_more_details?

Contributor

nikomatsakis commented Nov 18, 2014

Isn't the convention not new_with_more_details but rather with_more_details?

@aturon

This comment has been minimized.

Show comment
Hide comment
@aturon

aturon Nov 18, 2014

Member

@nikomatsakis

Isn't the convention not new_with_more_details but rather with_more_details?

Good catch! This was leftover from the original wiki that I started with. I will update.

Member

aturon commented Nov 18, 2014

@nikomatsakis

Isn't the convention not new_with_more_details but rather with_more_details?

Good catch! This was leftover from the original wiki that I started with. I will update.

@brson brson referenced this pull request in rust-lang/rust Nov 18, 2014

Closed

Tracking RFC 430 - conform to naming conventions #19091

@brson

This comment has been minimized.

Show comment
Hide comment
@brson

brson Nov 18, 2014

Contributor

Accepted. Discussion. Tracking.

Contributor

brson commented Nov 18, 2014

Accepted. Discussion. Tracking.

@brson brson closed this Nov 18, 2014

@brson

This comment has been minimized.

Show comment
Hide comment
@brson

brson Nov 18, 2014

Contributor

Accidentally rebased this instead of merged.

Contributor

brson commented Nov 18, 2014

Accidentally rebased this instead of merged.

alexcrichton added a commit to alexcrichton/rust that referenced this pull request Nov 20, 2014

Rename unwrap functions to into_inner
This change applies the conventions to unwrap listed in [RFC 430][rfc] to rename
non-failing `unwrap` methods to `into_inner`. This is a breaking change, but all
`unwrap` methods are retained as `#[deprecated]` for the near future. To update
code rename `unwrap` method calls to `into_inner`.

[rfc]: rust-lang/rfcs#430
[breaking-change]

cc #19091

@alexcrichton alexcrichton referenced this pull request in rust-lang/rust Nov 20, 2014

Merged

Rename unwrap functions to into_inner #19149

alexcrichton added a commit to alexcrichton/rust that referenced this pull request Nov 21, 2014

Rename unwrap functions to into_inner
This change applies the conventions to unwrap listed in [RFC 430][rfc] to rename
non-failing `unwrap` methods to `into_inner`. This is a breaking change, but all
`unwrap` methods are retained as `#[deprecated]` for the near future. To update
code rename `unwrap` method calls to `into_inner`.

[rfc]: rust-lang/rfcs#430
[breaking-change]

Closes #13159
cc #19091

alexcrichton added a commit to alexcrichton/rust that referenced this pull request Nov 21, 2014

Rename unwrap functions to into_inner
This change applies the conventions to unwrap listed in [RFC 430][rfc] to rename
non-failing `unwrap` methods to `into_inner`. This is a breaking change, but all
`unwrap` methods are retained as `#[deprecated]` for the near future. To update
code rename `unwrap` method calls to `into_inner`.

[rfc]: rust-lang/rfcs#430
[breaking-change]

Closes #13159
cc #19091

alexcrichton added a commit to alexcrichton/rust that referenced this pull request Nov 22, 2014

Rename unwrap functions to into_inner
This change applies the conventions to unwrap listed in [RFC 430][rfc] to rename
non-failing `unwrap` methods to `into_inner`. This is a breaking change, but all
`unwrap` methods are retained as `#[deprecated]` for the near future. To update
code rename `unwrap` method calls to `into_inner`.

[rfc]: rust-lang/rfcs#430
[breaking-change]

Closes #13159
cc #19091

alexcrichton added a commit to alexcrichton/rust that referenced this pull request Nov 23, 2014

Rename unwrap functions to into_inner
This change applies the conventions to unwrap listed in [RFC 430][rfc] to rename
non-failing `unwrap` methods to `into_inner`. This is a breaking change, but all
`unwrap` methods are retained as `#[deprecated]` for the near future. To update
code rename `unwrap` method calls to `into_inner`.

[rfc]: rust-lang/rfcs#430
[breaking-change]

Closes #13159
cc #19091

bors added a commit to rust-lang/rust that referenced this pull request Nov 25, 2014

auto merge of #19149 : alexcrichton/rust/issue-19091, r=aturon
This change applies the conventions to unwrap listed in [RFC 430][rfc] to rename
non-failing `unwrap` methods to `into_inner`. This is a breaking change, but all
`unwrap` methods are retained as `#[deprecated]` for the near future. To update
code rename `unwrap` method calls to `into_inner`.

[rfc]: rust-lang/rfcs#430
[breaking-change]

cc #19091

mzabaluev added a commit to mzabaluev/rust-c-str that referenced this pull request Nov 25, 2014

Rename unwrap functions to into_inner
Apply conventions described in [Rust RFC 430][rfc]
where `unwrap` is reserved for panicing methods.

[rfc]: rust-lang/rfcs#430

@Seeker14491 Seeker14491 referenced this pull request in rust-lang/rust-by-example Dec 21, 2015

Closed

generics/assoc_items: Confusing variable names #681

@chriskrycho chriskrycho referenced this pull request in rust-lang-nursery/reference Mar 29, 2017

Closed

Document all features #9

18 of 48 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment