RFC 0430: finalizing-naming-conventions

libs (convention)

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:

ItemConvention
Cratessnake_case (but prefer single word)
Modulessnake_case
TypesUpperCamelCase
TraitsUpperCamelCase
Enum variantsUpperCamelCase
Functionssnake_case
Methodssnake_case
General constructorsnew or with_more_details
Conversion constructorsfrom_some_other_type
Local variablessnake_case
Static variablesSCREAMING_SNAKE_CASE
Constant variablesSCREAMING_SNAKE_CASE
Type parametersconcise UpperCamelCase, usually single uppercase letter: T
Lifetimesshort, 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?