There's still a TODO here.

Perhaps it'd be helpful if this point was clarified like below (i.e. that "unit struct" refers to struct Foo; and not, e.g., struct Foo();).

Is there a reason this format is preferred over trailing , like in comma-separated lists, for consistency?

Personally I would have formatted it as follows had I had the choice, it would read like the spine of a list:

pub trait IndexRanges:
      Index<Range<usize>, Output=Self>
      Index<RangeTo<usize>, Output=Self>
      Index<RangeFrom<usize>, Output=Self>
      Index<RangeFull, Output=Self>
{
    ...
}

I do find that a at the end makes it harder to scan structure.

We're pretty consistent, throughout the document, of putting binary operators (or things that work like binary operators) at the starts of continuation lines.

What's the rationale for only permitting this for a single component? As long as it fits within a single line, it seems like multiple parameters would still be readable.

Where clauses get complicated quickly and can be very confusing even if they fit on one line. Furthermore, we reasoned that if a where clause is simple enough to justify being on one line, then it can nearly always be represented as bounds on generic arguments, rather than a where clause.

Nit: indentation.

It was decided to use UpperCamelCase rather than PascalCase.

Typo: "its".

I feel the wrapping style:

variable.foo()
        .bar()
        .baz(x, y, z);

should at least be mentioned (if not considered). This is quite prevalent in the Rust codebase and personally, I think it's easier to read than a single level of indentation (where possible). Has there been previous discussion about this?

Another style is:

variable
    .foo()
    .bar()
    .baz(x, y, z);

@Centril: this is mentioned lower down (I probably should have commented further down).

Ah, this point is mentioned in the (unlinked) guiding principles document. Smaller diffs should be generally preferred, but I wonder whether this particular point comes at the cost of readability.

Typo: "multi-line".

This is very much bike-shedding (sorry!), but I much prefer aligning the patterns (including the first), rather than the bars. Is there a good reason not to go for trailing |?

We're pretty consistent, throughout the document, of putting binary operators (or things that work like binary operators) at the starts of continuation lines.

I find this style hard to read; it obscures structure for me; I'd personally write this as (if it is long...):

let pattern
  : Type
  = expr;

I think the guideline as currently stated is more consistent. There's a stronger cohesion between pattern and Type from there being no space before the colon.
That motivates having pattern: Type on the same line.

@repax My point was mostly about pattern and = ; moving and aligning the = with the end of let becomes easier to scan imo; but I suppose it might not fit with the overall style.

I'm not sure how "prefer" can fit with "required for official Rust projects". Is it a violation of the rules if someone writes a doc-comment with //*?

This is phrasing to straddle the difference between what the Rust project requires, and what we think should be imposed on other comments. Inside the compiler/stdlib, and as far as I know, in all official projects, we require ///. However, while discussing making this a requirement, we decided to relax the wording to "prefer" over "require", as it felt like a bit of an over-reach to mandate this to everyone, and rustfmt basically doesn't touch comments already, so it woudn't even be enforced.

In other words, it's MUST for the Rust project, but SHOULD everywhere else.

Are the four spaces on this line intentional or not? And if they are intentional, are they normative or not?

That looks like a bug to me.

nitpick: I read "spaces around braces" as Error {err: u32} ,; perhaps inside braces instead?

Shouldn't we specify both around and inside the braces?

Error { err: u32 }

Or, "spaces around each individual brace." :P

This is a great file, but doesn't seemed to be linked from anywhere. Maybe reference it in the readme?

macro_export -> macro_use

I agree that re-debating is likely unhelpful, but it would be nice if more of the reasonings for the choices made it into the guide, or were easier to find from the relevant sections.

Maybe put more things into "overarching guidelines", and then include reasoning for any places were it's better do things differently? Some things that largely seem true, or were often repeated:

• keywords should have spaces around them
• put a space after {/before } (unless they end/start the line)
• no space before a semicolon
• single-line lists have separators; multi-line lists have terminators

I can see the rationale, but this suggestion seems very hard to enforce, esp. in combination with "a mechanical formatter should not change comments except to move them within a file".

Maybe the comment means "a mechanical formatter should not change comments except to move them within a line"?

s/struct/enum

Nevermind this actually. I see what is being said here.

By trailing whitespace, do you mean whitespace that trails a line comment? Or are you referring to any excessive whitespace immediately after a comment, e. g. 2 chars after a one-line block comment?

To which of the following cases would your rule apply?

Line comment

// This comment has trailing whitespace.       
                                        ^^^^^^^

Between block comment and closing sigil

pub fn foo(/* This is the foo implementation. */ x: T) {...}
pub fn bar(/* Like foo but with bar.          */ y: T) {...}
                                    ^^^^^^^^^

After the closing sigil

pub fn foo(/* This is the foo implementation. */ x: T) {...}
pub fn bar(/* Like foo but with bar. */          y: T) {...}
                                        ^^^^^^^^^

@claui given that the guide also says to prefer // to /*, I don't believe /* and stuff like this was taken into consideration; it's only talking about the line comment style.

that said, in general, we tend not to align things anyway, so it'd be

pub fn foo(/* This is the foo implementation. */ x: T) {...}
pub fn bar(/* Like foo but with bar. */ y: T) {...}

AFAIK.

it's only talking about the line comment style.

I see. Would it make sense to discourage the same thing for newlines in multi-line block comments?

“There should be no trailing whitespace after a line comment. Similarly, no line in a multi-line block comment should have trailing whitespace.”

The mixing of comma/vs-no comma for match arms always felt kind of inconsistent and annoying to manage as code evolves, so I've been setting match_block_trailing_comma = true. Was there any reasoning around going with match_block_trailing_comma = false as the default?

Oh, I see - seems to have been brought up way back in the match formatting RFC:

• match style-team#34 (comment)
• match style-team#34 (comment)
• match style-team#34 (comment)

Will we still have the option of configuring this in the future?

Probably yes, that seems to be a popular option.

Minor nitpick: the phrase is "barrier to entry"

Might I suggest converting this from a paragraph to a list?

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

There are too many "indentations" in this paragraph, imo.

Perhaps remove the second "discussion" in this sentence?

For more discussion on suitable heuristics, see this issue.

An example would go a long way here, to prevent any ambiguity.

I'm not sure these need to be a sub-list. I think it would read more clearly to remove the "is is either" bullet and pull the following two - lines back and make them * instead.

• If at the beginning of a line, do not put a space before the closure's opening |.
• If the closure is preceded by move, put a single space between move and the opening |.
• If the closure precedes an expression, put a single space between the closing | and the expression.
• Between the |s, use function definition syntax.
• Omit types where possible.

If possible, omit enclosing {}. However, there are a few circumstances under which {} should be used:

• When you have a return type.
• When there are statements.
• When there are comments in the body.
• When the body expression spans multiple lines and is a control-flow expression.

If using braces, follow the rules above for blocks. Examples:

"Additionally, there should be no space after ..."

Should be its and not it's

Proposed change:

include the try operator ?. For example:

its not it's

perhaps add a colon after indented and remove E.g.,

let x = |a| a; // a space before |
test( |a| a ); // a space before |

which one is extra space?

The latter. The former is covered by always putting spaces around =.