- Start Date: 2014-11-02
- RFC PR: rust-lang/rfcs#430
- Rust Issue: rust-lang/rust#19091
Summary
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.
Motivation
This is part of the ongoing conventions formalization process. The conventions described here have been loosely followed for a long time, but this RFC seeks to nail down a few final details and make them official.
Detailed design
General naming conventions
In general, Rust tends to use UpperCamelCase for “type-level” constructs
(types and traits) and snake_case for “value-level” constructs. More
precisely, the proposed (and mostly followed) conventions are:
| Item | Convention |
|---|---|
| Crates | snake_case (but prefer single word) |
| Modules | snake_case |
| Types | UpperCamelCase |
| Traits | UpperCamelCase |
| Enum variants | UpperCamelCase |
| Functions | snake_case |
| Methods | snake_case |
| General constructors | new or with_more_details |
| Conversion constructors | from_some_other_type |
| Local variables | snake_case |
| Static variables | SCREAMING_SNAKE_CASE |
| Constant variables | SCREAMING_SNAKE_CASE |
| Type parameters | concise UpperCamelCase, usually single uppercase letter: T |
| Lifetimes | short, lowercase: 'a |
Fine points
In UpperCamelCase, acronyms count as one word: use Uuid rather than
UUID. In snake_case, acronyms are lower-cased: is_xid_start.
In UpperCamelCase names multiple numbers can be separated by a _
for clarity: Windows10_1709 instead of Windows101709.
In snake_case or SCREAMING_SNAKE_CASE, a “word” should never
consist of a single letter unless it is the last “word”. So, we have
btree_map rather than b_tree_map, but PI_2 rather than PI2.
unwrap, into_foo and into_inner
There has been a long
running
debate
about the name of the
unwrap method found in Option and Result, but also a few other
standard library types. Part of the problem is that for some types
(e.g. BufferedReader), unwrap will never panic; but for Option
and Result calling unwrap is akin to asserting that the value is
Some/Ok.
There’s basic agreement that we should have an unambiguous term for
the Option/Result version of unwrap. Proposals have included
assert, ensure, expect, unwrap_or_panic and others; see the
links above for extensive discussion. No clear consensus has emerged.
This RFC proposes a simple way out: continue to call the methods
unwrap for Option and Result, and rename other uses of
unwrap to follow conversion conventions. Whenever possible, these
panic-free unwrapping operations should be into_foo for some
concrete foo, but for generic types like RefCell the name
into_inner will suffice. By convention, these into_ methods cannot
panic; and by (proposed) convention, unwrap should be reserved for
an into_inner conversion that can.
Drawbacks
Not really applicable; we need to finalize these conventions.
Unresolved questions
Are there remaining subtleties about the rules here that should be clarified?