rust
/
rfcs
mirror of https://github.com/rust-lang/rfcs
1
0
Fork 0
Code Issues Releases Wiki Activity

Address feedback

This commit is contained in:
Nick Cameron 2018-07-30 20:42:40 +12:00
parent ec3d345b7e
commit fc56a85671
7 changed files with 73 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
style-guide/README.md
View File

@ -13,7 +13,7 @@ communication overhead, and mental energy.
Humans comprehend information through pattern matching. By ensuring that all
Rust code has similar formatting, less mental effort is required to comprehend a
new project, lowering the bar to entry for new developers.
new project, lowering the barrier to entry for new developers.
Thus, there are productivity benefits to using a formatting tool (such as
rustfmt), and even larger benefits by using a community-consistent formatting,
@ -24,9 +24,11 @@ typically by using a formatting tool's default settings.
### Indentation and line width
Use spaces, not tabs. Each level of indentation must be four spaces. The maximum
width for a line is 100 characters. A tool should be configurable for all three
of these variables.
* Use spaces, not tabs.
* Each level of indentation must be four spaces (that is, all indentation
outside of string literals and comments must be a multiple of four).
* The maximum width for a line is 100 characters.
* A tool should be configurable for all three of these variables.
### Blank lines
@ -37,7 +39,7 @@ two newlines). E.g,
```rust
fn foo() {
let x = ...;
let y = ...;
let z = ...;
}
@ -60,10 +62,8 @@ defaults for both statements and items should be minimum: 1, maximum: 2.
### Comments
The following guidelines are recommendations only, a mechanical formatter should
not change comments except to move them within a file. To be clear this means
changing the whitespace before a line comment or the whitespace before or after
a block comment.
The following guidelines for comments are recommendations only, a mechanical
formatter might skip formatting of comments.
Prefer line comments (`//`) to block comments (`/* ... */`).
@ -76,7 +76,8 @@ have a newline after the opening sigil and before the closing sigil.
Prefer to put a comment on its own line. Where a comment follows code, there
should be a single space before it. Where a block comment is inline, there
should be surrounding whitespace as if it were an identifier or keyword. There
should be no trailing whitespace after a comment. Examples:
should be no trailing whitespace after a comment or at the end of any line in a
multi-line comment. Examples:
```rust
// A comment on an item.
@ -129,9 +130,9 @@ Doc comments should come before attributes.
### Attributes
Put each attribute on its own line, indented to the indentation of its item.
In the case of inner attributes (`#!`), indent it to the inner indentation (the
indentation of the item + 1). Prefer outer attributes, where possible.
Put each attribute on its own line, indented to the level of the item.
In the case of inner attributes (`#!`), indent it to the level of the inside of
the item. Prefer outer attributes, where possible.
For attributes with argument lists, format like functions.
@ -176,7 +177,7 @@ circumstances.
Some suitable heuristics are the size of the item (in characters) or the
complexity of an item (for example, that all components must be simple names,
not more complex sub-expressions). For more discussion on suitable heuristics,
see the discussion on [this issue](https://github.com/rust-lang-nursery/fmt-rfcs/issues/47).
see [this issue](https://github.com/rust-lang-nursery/fmt-rfcs/issues/47).
Tools should give the user an option to ignore such heuristics and always use
the normal formatting.
@ -185,3 +186,5 @@ the normal formatting.
## [Non-formatting conventions](advice.md)
## [Cargo.toml conventions](cargo.md)
## [Principles used for deciding these guidelines](principles.md)

7
style-guide/advice.md
View File

@ -18,15 +18,16 @@ if y {
## Names
* Types shall be `PascalCase`,
* Enum variants shall be `PascalCase`,
* Types shall be `UpperCamelCase`,
* Enum variants shall be `UpperCamelCase`,
* Struct fields shall be `snake_case`,
* Function and method names shall be `snake_case`,
* Local variables shall be `snake_case`,
* Macro names shall be `snake_case`,
* Constants (`const`s and immutable `static`s) shall be `SCREAMING_SNAKE_CASE`.
* When a name is forbidden because it is a reserved word (e.g., `crate`), use a
trailing underscore to make the name legal (e.g., `crate_`).
trailing underscore to make the name legal (e.g., `crate_`), or use raw
identifiers if possible.
### Modules

2
style-guide/cargo.md
View File

@ -70,7 +70,7 @@ example, `MIT/Apache-2.0`.)
The homepage field, if present, must consist of a single URL, including the
scheme (e.g. `https://example.org/`, not just `example.org`.)
Within the description field, wrap text at 78 columns. Don't start the
Within the description field, wrap text at 80 columns. Don't start the
description field with the name of the crate (e.g. "cratename is a ..."); just
describe the crate itself. If providing a multi-sentence description, the first
sentence should go on a line by itself and summarize the crate, like the

49
style-guide/expressions.md
View File

@ -60,9 +60,8 @@ An empty block should be written as `{}`.
A block may be written on a single line if:
* it is either
- used in expression position (not statement position)
- is an unsafe block in statement position
* it is either used in expression position (not statement position) or is an
unsafe block in statement position
* contains a single-line expression and no statements
* contains no comments
@ -118,7 +117,7 @@ fn main() {
### Closures
Don't put any extra spaces before the first `|` (unless the closure is prefixed
by `move`), but put a space between the second `|` and the expression of the
by `move`); put a space between the second `|` and the expression of the
closure. Between the `|`s, you should use function definition syntax, however,
elide types where possible.
@ -185,7 +184,7 @@ let f = Foo {
Use a single-line form where possible. There should not be spaces around the
parentheses. Where a single-line form is not possible, each element of the tuple
should be on it's own block-indented line and there should be a trailing comma.
should be on its own block-indented line and there should be a trailing comma.
```rust
(a, b, c)
@ -416,11 +415,11 @@ let cstr = "Hi\0" as *const str as *const [u8] as *const std::os::raw::c_char;
### Chains of fields and method calls
A chain is a sequence of field accesses and/or method calls. A chain may also
include the try operator. E.g., `a.b.c().d` or `foo?.bar().baz?`.
include the try operator ('?'). E.g., `a.b.c().d` or `foo?.bar().baz?`.
Prefer formatting on one line if possible, and the chain is *small*. If
formatting on multiple lines, each field access or method call in the chain
should be on it's own line with the line-break before the `.` and after any `?`.
should be on its own line with the line-break before the `.` and after any `?`.
Each line should be block-indented. E.g.,
```rust
@ -429,7 +428,7 @@ let foo = bar
.qux();
```
If the length of the last line of the first element plus it's indentation is
If the length of the last line of the first element plus its indentation is
less than or equal to the indentation of the second line (and there is space),
then combine the first and second lines, e.g.,
@ -467,7 +466,7 @@ a.b.c()?.d
Note there is block indent due to the chain and the function call in the above
example.
Prefer formatting the whole chain in mulit-line style and each element on one
Prefer formatting the whole chain in multi-line style and each element on one
line, rather than putting some elements on multiple lines and some on a single
line, e.g.,
@ -490,8 +489,8 @@ This section covers `if`, `if let`, `loop`, `while`, `while let`, and `for`
expressions.
The keyword, any initial clauses, and the opening brace of the block should be
on a single line. The usual rules for block formatting should be applied to the
block.
on a single line. The usual rules for [block formatting](#Blocks) should be
applied to the block.
If there is an `else` component, then the closing brace, `else`, any following
clause, and the opening brace should all be on the same line. There should be a
@ -614,6 +613,21 @@ match foo {
}
```
Prefer
```rust
match foo {
foo => bar,
a_very_long_pattern
| another_pattern
| yet_another_pattern
| a_forth_pattern => {
...
}
}
```
Avoid splitting the left-hand side (before the `=>`) of a match arm where
possible. If the right-hand side of the match arm is kept on the same line,
never use a block (unless the block is empty).
@ -724,6 +738,19 @@ clause, then you must use the above form:
}
```
If the pattern is multi-line, and the last line is less wide than the indent, do
not put the `if` clause on a newline. E.g.,
```rust
Token::Dimension {
value,
ref unit,
..
} if num_context.is_ok(context.parsing_mode, value) => {
...
}
```
If every clause in a pattern is *small*, but does not fit on one line, then the
pattern may be formatted across multiple lines with as many clauses per line as
possible. Again break before a `|`:

17
style-guide/items.md
View File

@ -8,7 +8,7 @@ must come before other items. We recommend that imports come before module
declarations; if imports and modules are separated, then they should be ordered
alphabetically. When sorting, `self` and `super` must come before any other
names. Module declarations should not be moved if they are annotated with
`#[macro_export]`, since that may be semantics changing.
`#[macro_use]`, since that may be semantics changing.
Tools should make the above ordering optional.
@ -77,9 +77,9 @@ enum FooBar {
}
```
If a struct variant is *short* (TODO link to definition), it may be formatted on
If a struct variant is [*small*](#small-items), it may be formatted on
one line. In this case, do not use a trailing comma for the field list, but do
put spaces around braces:
put spaces around each brace:
```rust
enum FooBar {
@ -118,7 +118,8 @@ struct Foo {
}
```
Prefer using a unit struct to an empty struct (these only exist to simplify code
Prefer using a unit struct (e.g., `struct Foo;`) to an empty struct (e.g.,
`struct Foo();` or `struct Foo {}`, these only exist to simplify code
generation), but if you must use an empty struct, keep it on one line with no
space between the braces: `struct Foo;` or `struct Foo {}`.
@ -214,7 +215,7 @@ impl Bar for Foo {
Avoid line-breaking in the signature if possible. If a line break is required in
a non-inherent impl, break immediately before `for`, block indent the concrete type
and put the opening brace on it's own line:
and put the opening brace on its own line:
```rust
impl Bar
@ -425,7 +426,7 @@ associated type has a bound, there should be a space after the colon but not
before:
```rust
pub type Foo: Bar;
pub type Foo: Bar;
```
@ -521,7 +522,7 @@ example, `a::*` comes before `b::a` but `a::b` comes before `a::*`. E.g.,
Tools must make the following normalisations:
* `use a::self;` -> `use a;`
* `use a::{};` ->
* `use a::{};` -> (nothing)
* `use a::{b};` -> `use a::b;`
And must apply these recursively.
@ -541,8 +542,8 @@ For example,
```rust
use a::b::{
x, y, z,
w::{...},
u::{...},
w::{...},
};
```

4
style-guide/statements.md
View File

@ -43,7 +43,7 @@ let Foo {
Foo { f, g };
let (abcd,
defg):
defg):
Baz =
{ ... }
```
@ -116,7 +116,9 @@ a_macro!(...);
There should be no space between the expression and the semi-colon.
```
<expr>;
```
All expressions in statement position should be terminated with a semi-colon,
unless they end with a block or are used as the value for a block.

2
text/0000-style-guide.md
View File

@ -30,7 +30,7 @@ Rustfmt has many options for customising formatting. The behaviour of those opti
# Guide-level explanation
[guide-level-explanation]: #guide-level-explanation
See the [guide text](../guide/README.md).
See the [guide text](../style-guide/README.md).
The style guide lives in the RFC repo, since it can be considered an appendix to this RFC. We might want to duplicate the style guide elsewhere to make it more discoverable, but the version here will be the 'source of truth'. Amendments to the style guide should go through the RFC process.