3 `extern crate` statements must be first in a file. They must be ordered
6 `use` statements, and module *declarations* (`mod foo;`, not `mod { ... }`)
7 must come before other items. We recommend that imports come before module
8 declarations; if imports and modules are separated, then they should be ordered
9 alphabetically. When sorting, `self` and `super` must come before any other
10 names. Module declarations should not be moved if they are annotated with
11 `#[macro_use]`, since that may be semantics changing.
13 Tools should make the above ordering optional.
16 ### Function definitions
18 In Rust, one finds functions by searching for `fn [function-name]`; It's
19 important that you style your code so that it's very searchable in this way.
21 The proper ordering and spacing is:
24 [pub] [unsafe] [extern ["ABI"]] fn foo(arg1: i32, arg2: i32) -> i32 {
29 Avoid comments within the signature itself.
31 If the function signature does not fit on one line, then break after the opening
32 parenthesis and before the closing parenthesis and put each argument on its own
33 block-indented line. For example,
44 Note the trailing comma on the last argument.
47 ### Tuples and tuple structs
49 Write the type list as you would a parameter list to a function.
51 Build a tuple or tuple struct as you would call a function.
56 struct Bar(Type1, Type2);
64 In the declaration, put each variant on its own line, block indented.
66 Format each variant accordingly as either a struct, tuple struct, or identifier,
67 which doesn't require special formatting (but without the `struct` keyword.
80 If a struct variant is [*small*](index.html#small-items), it may be formatted on
81 one line. In this case, do not use a trailing comma for the field list, but do
82 put spaces around each brace:
86 Error { err: Box<Error>, line: u32 },
90 In an enum with multiple struct variants, if any struct variant is written on
91 multiple lines, then the multi-line formatting should be used for all struct
92 variants. However, such a situation might be an indication that you should
93 factor out the fields of the variant into their own struct.
96 ### Structs and Unions
98 Struct names follow on the same line as the `struct` keyword, with the opening
99 brace on the same line when it fits within the right margin. All struct fields
100 are indented once and end with a trailing comma. The closing brace is not
101 indented and appears on its own line.
110 If and only if the type of a field does not fit within the right margin, it is
111 pulled down to its own line and indented again.
121 Prefer using a unit struct (e.g., `struct Foo;`) to an empty struct (e.g.,
122 `struct Foo();` or `struct Foo {}`, these only exist to simplify code
123 generation), but if you must use an empty struct, keep it on one line with no
124 space between the braces: `struct Foo;` or `struct Foo {}`.
126 The same guidelines are used for untagged union declarations.
140 Put the whole struct on one line if possible. Types in the parentheses should be
141 separated by a comma and space with no trailing comma. No spaces around the
142 parentheses or semi-colon:
145 pub struct Foo(String, u8);
148 Prefer unit structs to empty tuple structs (these only exist to simplify code
149 generation), e.g., `struct Foo;` rather than `struct Foo();`.
151 For more than a few fields, prefer a proper struct with named fields. Given
152 this, a tuple struct should always fit on one line. If it does not, block format
153 the fields with a field on each line and a trailing comma:
165 Trait items should be block-indented. If there are no items, the trait may be
166 formatted on a single line. Otherwise there should be line-breaks after the
167 opening brace and before the closing brace:
177 If the trait has bounds, there should be a space after the colon but not before
178 and before and after each `+`, e.g.,
181 trait Foo: Debug + Bar {}
184 Prefer not to line-break in the bounds if possible (consider using a `where`
185 clause). Prefer to break between bounds than to break any individual bound. If
186 you must break the bounds, put each bound (including the first) on its own
187 block-indented line, break before the `+` and put the opening brace on its own
191 pub trait IndexRanges:
192 Index<Range<usize>, Output=Self>
193 + Index<RangeTo<usize>, Output=Self>
194 + Index<RangeFrom<usize>, Output=Self>
195 + Index<RangeFull, Output=Self>
204 Impl items should be block indented. If there are no items, the impl may be
205 formatted on a single line. Otherwise there should be line-breaks after the
206 opening brace and before the closing brace:
216 Avoid line-breaking in the signature if possible. If a line break is required in
217 a non-inherent impl, break immediately before `for`, block indent the concrete type
218 and put the opening brace on its own line:
233 Use spaces around keywords, no spaces around the semi-colon.
247 Use spaces around keywords and before the opening brace, no spaces around the
252 Use `{}` for the full definition of the macro.
262 Prefer to put a generics clause on one line. Break other parts of an item
263 declaration rather than line-breaking a generics clause. If a generics clause is
264 large enough to require line-breaking, you should prefer to use a `where` clause
267 Do not put spaces before or after `<` nor before `>`. Only put a space after `>`
268 if it is followed by a word or opening brace, not an opening parenthesis. There
269 should be a space after each comma and no trailing comma.
272 fn foo<T: Display, U: Debug>(x: Vec<T>, y: Vec<U>) ...
274 impl<T: Display, U: Debug> SomeType<T, U> { ...
277 If the generics clause must be formatted across multiple lines, each parameter
278 should have its own block-indented line, there should be newlines after the
279 opening bracket and before the closing bracket, and the should be a trailing
286 >(x: Vec<T>, y: Vec<U>) ...
289 If an associated type is bound in a generic type, then there should be spaces on
290 either side of the `=`:
293 <T: Example<Item = u32>>
296 Prefer to use single-letter names for generic parameters.
301 These rules apply for `where` clauses on any item.
303 A `where` clause may immediately follow a closing bracket of any kind.
304 Otherwise, it must start a new line, with no indent. Each component of a `where`
305 clause must be on its own line and be block indented. There should be a trailing
306 comma, unless the clause is terminated with a semicolon. If the `where` clause
307 is followed by a block (or assignment), the block should be started on a new
311 fn function<T, U>(args)
342 U: AnotherBound; // Note, no trailing comma.
344 // Note that where clauses on `type` aliases are not enforced and should not
352 If a `where` clause is very short, we recommend using an inline bound on the
356 If a component of a `where` clause is long, it may be broken before `+` and
357 further block indented. Each bound should go on its own line. E.g.,
360 impl<T: ?Sized, Idx> IndexRanges<Idx> for T
362 T: Index<Range<Idx>, Output = Self::Output>
363 + Index<RangeTo<Idx>, Output = Self::Output>
364 + Index<RangeFrom<Idx>, Output = Self::Output>
365 + Index<RangeInclusive<Idx>, Output = Self::Output>
366 + Index<RangeToInclusive<Idx>, Output = Self::Output> + Index<RangeFull>
369 #### Option - `where_single_line`
371 `where_single_line` is `false` by default. If `true`, then a where clause with
372 exactly one component may be formatted on a single line if the rest of the
373 item's signature is also kept on one line. In this case, there is no need for a
374 trailing comma and if followed by a block, no need for a newline before the
378 // May be single-lined.
379 fn foo<T>(args) -> ReturnType
384 // Must be multi-lined.
398 Type aliases should generally be kept on one line. If necessary to break the
399 line, do so after the `=`; the right-hand-side should be block indented:
402 pub type Foo = Bar<T>;
404 // If multi-line is required
405 type VeryLongType<T, U: SomeBound> =
406 AnEvenLongerType<T, U, Foo<T>>;
409 Where possible avoid `where` clauses and keep type constraints inline. Where
410 that is not possible split the line before and after the `where` clause (and
411 split the `where` clause as normal), e.g.,
414 type VeryLongType<T, U>
416 T: U::AnAssociatedType,
418 = AnEvenLongerType<T, U, Foo<T>>;
424 Associated types should follow the guidelines above for type aliases. Where an
425 associated type has a bound, there should be a space after the colon but not
435 When writing extern items (such as `extern "C" fn`), always be explicit about
436 the ABI. For example, write `extern "C" fn foo ...`, not `extern fn foo ...`, or
437 `extern "C" { ... }`.
440 ### Imports (`use` statements)
442 If an import can be formatted on one line, do so. There should be no spaces
448 use a::b::{foo, bar, baz};
452 #### Large list imports
454 Prefer to use multiple imports rather than a multi-line import. However, tools
455 should not split imports by default (they may offer this as an option).
457 If an import does require multiple lines (either because a list of single names
458 does not fit within the max width, or because of the rules for nested imports
459 below), then break after the opening brace and before the closing brace, use a
460 trailing comma, and block indent the names.
465 foo::{long, list, of, imports};
466 foo::{more, imports};
470 long, list, of, imports, more,
471 imports, // Note trailing comma
476 #### Ordering of imports
478 A *group* of imports is a set of imports on the same or sequential lines. One or
479 more blank lines or other items (e.g., a function) separate groups of imports.
481 Within a group of imports, imports must be sorted ascii-betically. Groups of
482 imports must not be merged or re-ordered.
505 Because of `macro_use`, attributes must also start a new group and prevent
508 Note that tools which only have access to syntax (such as Rustfmt) cannot tell
509 which imports are from an external crate or the std lib, etc.
512 #### Ordering list import
514 Names in a list import must be sorted ascii-betically, but with `self` and
515 `super` first, and groups and glob imports last. This applies recursively. For
516 example, `a::*` comes before `b::a` but `a::b` comes before `a::*`. E.g.,
517 `use foo::bar::{a, b::c, b::d, b::d::{x, y, z}, b::{self, r, s}};`.
522 Tools must make the following normalisations:
524 * `use a::self;` -> `use a;`
525 * `use a::{};` -> (nothing)
526 * `use a::{b};` -> `use a::b;`
528 And must apply these recursively.
530 Tools must not otherwise merge or un-merge import lists or adjust glob imports
531 (without an explicit option).
536 If there are any nested imports in a list import, then use the multi-line form,
537 even if the import fits on one line. Each nested import must be on its own line,
538 but non-nested imports must be grouped on as few lines as possible.
551 #### Merging/un-merging imports
564 Tools must not merge or un-merge imports by default. They may offer merging or
565 un-merging as an option.