Address feedback

Author: nrc

style-guide/README.md

@@ -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)

style-guide/advice.md

@@ -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
 

style-guide/cargo.md

@@ -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

style-guide/expressions.md

@@ -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 `|`:

style-guide/items.md

@@ -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::{...},
 };
 ```
 

style-guide/statements.md

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

text/0000-style-guide.md

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