[rustc.git] / src / doc / style / style / naming / README.md

% Naming conventions

### General conventions [RFC #430]

> The guidelines below were approved by [RFC #430](https://github.com/rust-lang/rfcs/pull/430).

In general, Rust tends to use `CamelCase` for "type-level" constructs
(types and traits) and `snake_case` for "value-level" constructs. More
precisely:

| Item | Convention |
| ---- | ---------- |
| Crates | `snake_case` (but prefer single word) |
| Modules | `snake_case` |
| Types | `CamelCase` |
| Traits | `CamelCase` |
| Enum variants | `CamelCase` |
| 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 `CamelCase`, usually single uppercase letter: `T` |
| Lifetimes | short, lowercase: `'a` |

<p>
In `CamelCase`, acronyms count as one word: use `Uuid` rather than
`UUID`.  In `snake_case`, acronyms are lower-cased: `is_xid_start`.

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`.

### Referring to types in function/method names [RFC 344]

> The guidelines below were approved by [RFC #344](https://github.com/rust-lang/rfcs/pull/344).

Function names often involve type names, the most common example being conversions
like `as_slice`. If the type has a purely textual name (ignoring parameters), it
is straightforward to convert between type conventions and function conventions:

Type name | Text in methods
--------- | ---------------
`String`  | `string`
`Vec<T>`  | `vec`
`YourType`| `your_type`

Types that involve notation follow the convention below. There is some
overlap on these rules; apply the most specific applicable rule:

Type name | Text in methods
--------- | ---------------
`&str`    | `str`
`&[T]`    | `slice`
`&mut [T]`| `mut_slice`
`&[u8]`   | `bytes`
`&T`      | `ref`
`&mut T`  | `mut`
`*const T`| `ptr`
`*mut T`  | `mut_ptr`

### Avoid redundant prefixes [RFC 356]

> The guidelines below were approved by [RFC #356](https://github.com/rust-lang/rfcs/pull/356).

Names of items within a module should not be prefixed with that module's name:

Prefer

``` rust
mod foo {
    pub struct Error { ... }
}
```

over

``` rust
mod foo {
    pub struct FooError { ... }
}
```

This convention avoids stuttering (like `io::IoError`). Library clients can
rename on import to avoid clashes.

### Getter/setter methods [RFC 344]

> The guidelines below were approved by [RFC #344](https://github.com/rust-lang/rfcs/pull/344).

Some data structures do not wish to provide direct access to their fields, but
instead offer "getter" and "setter" methods for manipulating the field state
(often providing checking or other functionality).

The convention for a field `foo: T` is:

* A method `foo(&self) -> &T` for getting the current value of the field.
* A method `set_foo(&self, val: T)` for setting the field. (The `val` argument
  here may take `&T` or some other type, depending on the context.)

Note that this convention is about getters/setters on ordinary data types, *not*
on [builder objects](../../ownership/builders.html).

### Escape hatches [FIXME]

> **[FIXME]** Should we standardize a convention for functions that may break API
> guarantees? e.g. `ToCStr::to_c_str_unchecked`

### Predicates

* Simple boolean predicates should be prefixed with `is_` or another
  short question word, e.g., `is_empty`.
* Common exceptions: `lt`, `gt`, and other established predicate names.
Commit	Line	Data
85aaf69f SL	1	% Naming conventions
	2
	3	### General conventions [RFC #430]
	4
	5	> The guidelines below were approved by [RFC #430](https://github.com/rust-lang/rfcs/pull/430).
	6
	7	In general, Rust tends to use `CamelCase` for "type-level" constructs
	8	(types and traits) and `snake_case` for "value-level" constructs. More
	9	precisely:
	10
	11	\| Item \| Convention \|
	12	\| ---- \| ---------- \|
	13	\| Crates \| `snake_case` (but prefer single word) \|
	14	\| Modules \| `snake_case` \|
	15	\| Types \| `CamelCase` \|
	16	\| Traits \| `CamelCase` \|
	17	\| Enum variants \| `CamelCase` \|
	18	\| Functions \| `snake_case` \|
	19	\| Methods \| `snake_case` \|
	20	\| General constructors \| `new` or `with_more_details` \|
	21	\| Conversion constructors \| `from_some_other_type` \|
	22	\| Local variables \| `snake_case` \|
	23	\| Static variables \| `SCREAMING_SNAKE_CASE` \|
	24	\| Constant variables \| `SCREAMING_SNAKE_CASE` \|
	25	\| Type parameters \| concise `CamelCase`, usually single uppercase letter: `T` \|
	26	\| Lifetimes \| short, lowercase: `'a` \|
	27
	28	<p>
	29	In `CamelCase`, acronyms count as one word: use `Uuid` rather than
	30	`UUID`. In `snake_case`, acronyms are lower-cased: `is_xid_start`.
	31
	32	In `snake_case` or `SCREAMING_SNAKE_CASE`, a "word" should never
	33	consist of a single letter unless it is the last "word". So, we have
	34	`btree_map` rather than `b_tree_map`, but `PI_2` rather than `PI2`.
	35
	36	### Referring to types in function/method names [RFC 344]
	37
	38	> The guidelines below were approved by [RFC #344](https://github.com/rust-lang/rfcs/pull/344).
	39
	40	Function names often involve type names, the most common example being conversions
	41	like `as_slice`. If the type has a purely textual name (ignoring parameters), it
	42	is straightforward to convert between type conventions and function conventions:
	43
	44	Type name \| Text in methods
	45	--------- \| ---------------
	46	`String` \| `string`
	47	`Vec<T>` \| `vec`
	48	`YourType`\| `your_type`
	49
	50	Types that involve notation follow the convention below. There is some
	51	overlap on these rules; apply the most specific applicable rule:
	52
	53	Type name \| Text in methods
	54	--------- \| ---------------
	55	`&str` \| `str`
	56	`&[T]` \| `slice`
	57	`&mut [T]`\| `mut_slice`
	58	`&[u8]` \| `bytes`
	59	`&T` \| `ref`
	60	`&mut T` \| `mut`
	61	`*const T`\| `ptr`
	62	`*mut T` \| `mut_ptr`
	63
	64	### Avoid redundant prefixes [RFC 356]
65
66	> The guidelines below were approved by [RFC #356](https://github.com/rust-lang/rfcs/pull/356).
67
68	Names of items within a module should not be prefixed with that module's name:
69
70	Prefer
71
72	``` rust
73	mod foo {
74	pub struct Error { ... }
75	}
76	```
77
78	over
79
80	``` rust
81	mod foo {
82	pub struct FooError { ... }
83	}
84	```
85
86	This convention avoids stuttering (like `io::IoError`). Library clients can
87	rename on import to avoid clashes.
88
89	### Getter/setter methods [RFC 344]
90
91	> The guidelines below were approved by [RFC #344](https://github.com/rust-lang/rfcs/pull/344).
92
93	Some data structures do not wish to provide direct access to their fields, but
94	instead offer "getter" and "setter" methods for manipulating the field state
95	(often providing checking or other functionality).
96
97	The convention for a field `foo: T` is:
98
99	* A method `foo(&self) -> &T` for getting the current value of the field.
100	* A method `set_foo(&self, val: T)` for setting the field. (The `val` argument
101	here may take `&T` or some other type, depending on the context.)
102
103	Note that this convention is about getters/setters on ordinary data types, not
54a0048b	104	on [builder objects](../../ownership/builders.html).
85aaf69f SL	105
	106	### Escape hatches [FIXME]
	107
	108	> [FIXME] Should we standardize a convention for functions that may break API
	109	> guarantees? e.g. `ToCStr::to_c_str_unchecked`
	110
	111	### Predicates
	112
	113	* Simple boolean predicates should be prefixed with `is_` or another
	114	short question word, e.g., `is_empty`.
	115	* Common exceptions: `lt`, `gt`, and other established predicate names.