From 3747d7f593555cdf25d35aeaae8a66d5018eadbf Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 12:30:14 -0700 Subject: [PATCH 01/15] style-guide: Move text about block vs visual indent to indentation section `principles.md` includes some high-level guiding principles for formatting, but also includes a few specific formatting provisions. While those provisions apply in many places, the same holds true for other high-level guidance, such as the indentation section. Move the text about using block indent rather than visual indent to the indentation section, so that `principles.md` can focus on guiding principles while the top level of the style guide gives concrete formatting recommendations. --- src/doc/style-guide/src/README.md | 18 ++++++++++++++++++ src/doc/style-guide/src/principles.md | 17 ----------------- 2 files changed, 18 insertions(+), 17 deletions(-) diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md index adb73a7eef6e0..49a4bce2f5dcd 100644 --- a/src/doc/style-guide/src/README.md +++ b/src/doc/style-guide/src/README.md @@ -30,6 +30,24 @@ typically by using a formatting tool's default settings. * The maximum width for a line is 100 characters. * A tool should be configurable for all three of these variables. +#### Block indent + +Prefer block indent over visual indent: + +```rust +// Block indent +a_function_call( + foo, + bar, +); + +// Visual indent +a_function_call(foo, + bar); +``` + +This makes for smaller diffs (e.g., if `a_function_call` is renamed in the above +example) and less rightward drift. ### Blank lines diff --git a/src/doc/style-guide/src/principles.md b/src/doc/style-guide/src/principles.md index 2d203f264e623..c3104e6d9b60f 100644 --- a/src/doc/style-guide/src/principles.md +++ b/src/doc/style-guide/src/principles.md @@ -31,23 +31,6 @@ following principles (in rough priority order): ## Overarching guidelines -Prefer block indent over visual indent. E.g., - -```rust -// Block indent -a_function_call( - foo, - bar, -); - -// Visual indent -a_function_call(foo, - bar); -``` - -This makes for smaller diffs (e.g., if `a_function_call` is renamed in the above -example) and less rightward drift. - Lists should have a trailing comma when followed by a newline, see the block indent example above. This choice makes moving code (e.g., by copy and paste) easier and makes smaller diffs. From 92805672c3703c43481103bd1e81b12844a87b74 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 12:41:30 -0700 Subject: [PATCH 02/15] style-guide: Move and expand text about trailing commas `principles.md` includes some high-level guiding principles for formatting, but also includes a few specific formatting provisions. While those provisions apply in many places, the same holds true for other high-level guidance. Move the text about trailing commas to `README.md`, so that `principles.md` can focus on guiding principles while the top level of the style guide gives concrete formatting recommendations. --- src/doc/style-guide/src/README.md | 21 +++++++++++++++++++++ src/doc/style-guide/src/principles.md | 7 ------- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md index 49a4bce2f5dcd..3d47e33841a54 100644 --- a/src/doc/style-guide/src/README.md +++ b/src/doc/style-guide/src/README.md @@ -49,6 +49,27 @@ a_function_call(foo, This makes for smaller diffs (e.g., if `a_function_call` is renamed in the above example) and less rightward drift. +### Trailing commas + +Lists should have a trailing comma when followed by a newline: + +```rust +function_call( + argument, + another_argument, +); + +let array = [ + element, + another_element, + yet_another_element, +]; +``` + +This makes moving code (e.g., by copy and paste) easier, and makes diffs +smaller, as appending or removing items does not require modifying another line +to add or remove a comma. + ### Blank lines Separate items and statements by either zero or one blank lines (i.e., one or diff --git a/src/doc/style-guide/src/principles.md b/src/doc/style-guide/src/principles.md index c3104e6d9b60f..c86121e6a4697 100644 --- a/src/doc/style-guide/src/principles.md +++ b/src/doc/style-guide/src/principles.md @@ -27,10 +27,3 @@ following principles (in rough priority order): - ease of implementation (in Rustfmt, and in other tools/editors/code generators) - internal consistency - simplicity of formatting rules - - -## Overarching guidelines - -Lists should have a trailing comma when followed by a newline, see the block -indent example above. This choice makes moving code (e.g., by copy and paste) -easier and makes smaller diffs. From 2c0dd90936a5ce6a61cbe0f342b452871409b71c Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 12:42:57 -0700 Subject: [PATCH 03/15] style-guide: s/right-ward/rightward/ We already use the word "rightward" elsewhere; avoid the unnecessarily hyphenated "right-ward". --- src/doc/style-guide/src/principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/style-guide/src/principles.md b/src/doc/style-guide/src/principles.md index c86121e6a4697..30fb26014f272 100644 --- a/src/doc/style-guide/src/principles.md +++ b/src/doc/style-guide/src/principles.md @@ -19,7 +19,7 @@ following principles (in rough priority order): * specifics - compatibility with version control practices - preserving diffs, merge-friendliness, etc. - - preventing right-ward drift + - preventing rightward drift - minimising vertical space * application From 4c5bb06a97515c1135e9339e6fa1fd78e7531ba2 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 12:45:56 -0700 Subject: [PATCH 04/15] style-guide: Consistently refer to rustfmt as `rustfmt` --- src/doc/style-guide/src/README.md | 4 ++-- src/doc/style-guide/src/items.md | 4 ++-- src/doc/style-guide/src/principles.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md index 3d47e33841a54..78e1d6a1fa184 100644 --- a/src/doc/style-guide/src/README.md +++ b/src/doc/style-guide/src/README.md @@ -16,8 +16,8 @@ Rust code has similar formatting, less mental effort is required to comprehend a 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, -typically by using a formatting tool's default settings. +`rustfmt`), and even larger benefits by using a community-consistent +formatting, typically by using a formatting tool's default settings. ## Formatting conventions diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md index 2835975355fca..a9c559d0bb8c9 100644 --- a/src/doc/style-guide/src/items.md +++ b/src/doc/style-guide/src/items.md @@ -505,8 +505,8 @@ use b; Because of `macro_use`, attributes must also start a new group and prevent re-ordering. -Note that tools which only have access to syntax (such as Rustfmt) cannot tell -which imports are from an external crate or the std lib, etc. +Note that tools which only have access to syntax (such as `rustfmt`) cannot +tell which imports are from an external crate or the std lib, etc. #### Ordering list import diff --git a/src/doc/style-guide/src/principles.md b/src/doc/style-guide/src/principles.md index 30fb26014f272..bbf6d76d4216e 100644 --- a/src/doc/style-guide/src/principles.md +++ b/src/doc/style-guide/src/principles.md @@ -24,6 +24,6 @@ following principles (in rough priority order): * application - ease of manual application - - ease of implementation (in Rustfmt, and in other tools/editors/code generators) + - ease of implementation (in `rustfmt`, and in other tools/editors/code generators) - internal consistency - simplicity of formatting rules From d270af31972b2673ef0b05a5749a49f8a68a3d2b Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 12:47:24 -0700 Subject: [PATCH 05/15] style-guide: Remove inaccurate statement about rustfmt rustfmt does include a mechanism to distinguish standard library imports, which it does syntactically by crate name. Avoid making a misleading statement that implies it cannot do this. --- src/doc/style-guide/src/items.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md index a9c559d0bb8c9..06ee4e28ccbc5 100644 --- a/src/doc/style-guide/src/items.md +++ b/src/doc/style-guide/src/items.md @@ -505,10 +505,6 @@ use b; Because of `macro_use`, attributes must also start a new group and prevent re-ordering. -Note that tools which only have access to syntax (such as `rustfmt`) cannot -tell which imports are from an external crate or the std lib, etc. - - #### Ordering list import Names in a list import must be sorted ascii-betically, but with `self` and From c5f8b2c7a92bc542c0c2666dc4672493cf945982 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 13:01:45 -0700 Subject: [PATCH 06/15] style-guide: Define (and capitalize) "ASCIIbetically" The style guide didn't give any definition for it. --- src/doc/style-guide/src/items.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md index 06ee4e28ccbc5..f1f5344f3e2cd 100644 --- a/src/doc/style-guide/src/items.md +++ b/src/doc/style-guide/src/items.md @@ -478,8 +478,8 @@ foo::{ A *group* of imports is a set of imports on the same or sequential lines. One or more blank lines or other items (e.g., a function) separate groups of imports. -Within a group of imports, imports must be sorted ascii-betically. Groups of -imports must not be merged or re-ordered. +Within a group of imports, imports must be sorted ASCIIbetically (uppercase +before lowercase). Groups of imports must not be merged or re-ordered. E.g., input: @@ -507,7 +507,7 @@ re-ordering. #### Ordering list import -Names in a list import must be sorted ascii-betically, but with `self` and +Names in a list import must be sorted ASCIIbetically, but with `self` and `super` first, and groups and glob imports last. This applies recursively. For example, `a::*` comes before `b::a` but `a::b` comes before `a::*`. E.g., `use foo::bar::{a, b::c, b::d, b::d::{x, y, z}, b::{self, r, s}};`. From 20f2828bbd37ce3d91797a2f2243c76190856301 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 13:12:43 -0700 Subject: [PATCH 07/15] style-guide: Update cargo.md for authors being optional and not recommended Change an example using the authors field to use a long feature list instead. Change the conventions for the authors field to say "if present". --- src/doc/style-guide/src/cargo.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/src/doc/style-guide/src/cargo.md b/src/doc/style-guide/src/cargo.md index 13b96ca8c5e9d..5e6a62a7fd284 100644 --- a/src/doc/style-guide/src/cargo.md +++ b/src/doc/style-guide/src/cargo.md @@ -25,16 +25,17 @@ not indent any key names; start all key names at the start of a line. Use multi-line strings (rather than newline escape sequences) for any string values that include multiple lines, such as the crate description. -For array values, such as a list of authors, put the entire list on the same +For array values, such as a list of features, put the entire list on the same line as the key, if it fits. Otherwise, use block indentation: put a newline after the opening square bracket, indent each item by one indentation level, put a comma after each item (including the last), and put the closing square bracket at the start of a line by itself after the last item. ```rust -authors = [ - "A Uthor ", - "Another Author ", +some_feature = [ + "another_feature", + "yet_another_feature", + "some_dependency?/some_feature", ] ``` @@ -54,11 +55,11 @@ version = "4.5.6" ## Metadata conventions -The authors list should consist of strings that each contain an author name -followed by an email address in angle brackets: `Full Name `. -It should not contain bare email addresses, or names without email addresses. -(The authors list may also include a mailing list address without an associated -name.) +The authors list, if present, should consist of strings that each contain an +author name followed by an email address in angle brackets: `Full Name +`. It should not contain bare email addresses, or names without +email addresses. (The authors list may also include a mailing list address +without an associated name.) The license field must contain a valid [SPDX expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60), From 6f8f83f66d88afe1e7d40011f8862844d8fa86c4 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 13:17:47 -0700 Subject: [PATCH 08/15] style-guide: Avoid normative recommendations for formatting tool configurability It's not within the scope of the style guide to tell formatting tools whether, or how, to allow configurability of non-default formatting. --- src/doc/style-guide/src/README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md index 78e1d6a1fa184..2ad834f804bd0 100644 --- a/src/doc/style-guide/src/README.md +++ b/src/doc/style-guide/src/README.md @@ -28,7 +28,7 @@ formatting, typically by using a formatting tool's default settings. * 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. +* A tool may choose to make some of these configurable. #### Block indent @@ -87,11 +87,7 @@ fn bar() {} fn baz() {} ``` -Formatting tools should make the bounds on blank lines configurable: there -should be separate minimum and maximum numbers of newlines between both -statements and (top-level) items (i.e., four options). As described above, the -defaults for both statements and items should be minimum: 1, maximum: 2. - +Formatting tools may wish to make the bounds on blank lines configurable. ### [Module-level items](items.md) ### [Statements](statements.md) From fec28b26b5b6252cdd153135d61f54de4f2d10fb Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 13:21:40 -0700 Subject: [PATCH 09/15] style-guide: Clarify advice on names matching keywords In particular, specify what this advice is an alternative to (creative misspellings such as `krate`). --- src/doc/style-guide/src/advice.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/style-guide/src/advice.md b/src/doc/style-guide/src/advice.md index ab4b92b0a2478..9a617be509c38 100644 --- a/src/doc/style-guide/src/advice.md +++ b/src/doc/style-guide/src/advice.md @@ -25,9 +25,9 @@ if y { * 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_`), or use raw - identifiers if possible. + * When a name is forbidden because it is a reserved word (such as `crate`), + either use a raw identifier (`r#crate`) or use a trailing underscore + (`crate_`). Don't misspell the word (`krate`). ### Modules From c930b21bcdf9a47fd299e150f8056fe5f7bd7a08 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 13:28:47 -0700 Subject: [PATCH 10/15] style-guide: Reword an awkwardly phrased recommendation (and fix a typo) --- src/doc/style-guide/src/items.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md index f1f5344f3e2cd..79635e758f31b 100644 --- a/src/doc/style-guide/src/items.md +++ b/src/doc/style-guide/src/items.md @@ -15,8 +15,8 @@ Tools should make the above ordering optional. ### Function definitions -In Rust, one finds functions by searching for `fn [function-name]`; It's -important that you style your code so that it's very searchable in this way. +In Rust, people often find functions by searching for `fn [function-name]`, so +the formatting of function definitions shold enable this. The proper ordering and spacing is: From 3e2449c2b14eb676a27d2b62a162a800c6e89212 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 13:30:06 -0700 Subject: [PATCH 11/15] style-guide: Rephrase a confusingly ordered, ambiguous sentence (and fix a typo) This sentence had a parenthetical without a closing parenthesis, and had the phrase "which doesn't require special formatting" ambiguously at the end of a list when it only applied to the last item of the list. --- src/doc/style-guide/src/items.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md index 79635e758f31b..41ac1eeca96a5 100644 --- a/src/doc/style-guide/src/items.md +++ b/src/doc/style-guide/src/items.md @@ -63,8 +63,9 @@ let y = (11, 22, 33); In the declaration, put each variant on its own line, block indented. -Format each variant accordingly as either a struct, tuple struct, or identifier, -which doesn't require special formatting (but without the `struct` keyword. +Format each variant accordingly as either a struct (but without the `struct` +keyword), a tuple struct, or an identifier (which doesn't require special +formatting): ```rust enum FooBar { From a9d1db31457f8ae619bb73234632b20ccc8b930f Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 13:57:49 -0700 Subject: [PATCH 12/15] style-guide: Avoid hyphenating "semicolon" --- src/doc/style-guide/src/items.md | 6 +++--- src/doc/style-guide/src/statements.md | 10 +++++----- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md index 41ac1eeca96a5..8a0954f53430e 100644 --- a/src/doc/style-guide/src/items.md +++ b/src/doc/style-guide/src/items.md @@ -140,7 +140,7 @@ union Foo { Put the whole struct on one line if possible. Types in the parentheses should be separated by a comma and space with no trailing comma. No spaces around the -parentheses or semi-colon: +parentheses or semicolon: ```rust pub struct Foo(String, u8); @@ -231,7 +231,7 @@ impl Bar `extern crate foo;` -Use spaces around keywords, no spaces around the semi-colon. +Use spaces around keywords, no spaces around the semicolon. ### Modules @@ -246,7 +246,7 @@ mod foo; ``` Use spaces around keywords and before the opening brace, no spaces around the -semi-colon. +semicolon. ### macro\_rules! diff --git a/src/doc/style-guide/src/statements.md b/src/doc/style-guide/src/statements.md index 671e6d31a5775..abb6b492b9121 100644 --- a/src/doc/style-guide/src/statements.md +++ b/src/doc/style-guide/src/statements.md @@ -1,7 +1,7 @@ ### Let statements There should be spaces after the `:` and on both sides of the `=` (if they are -present). No space before the semi-colon. +present). No space before the semicolon. ```rust // A comment. @@ -194,7 +194,7 @@ used to determine whether a let-else statement is *short*. ### Macros in statement position A macro use in statement position should use parentheses or square brackets as -delimiters and should be terminated with a semi-colon. There should be no spaces +delimiters and should be terminated with a semicolon. There should be no spaces between the name, `!`, the delimiters, or the `;`. ```rust @@ -205,13 +205,13 @@ a_macro!(...); ### Expressions in statement position -There should be no space between the expression and the semi-colon. +There should be no space between the expression and the semicolon. ``` ; ``` -All expressions in statement position should be terminated with a semi-colon, +All expressions in statement position should be terminated with a semicolon, unless they end with a block or are used as the value for a block. E.g., @@ -229,7 +229,7 @@ loop { } ``` -Use a semi-colon where an expression has void type, even if it could be +Use a semicolon where an expression has void type, even if it could be propagated. E.g., ```rust From 5d637219e43ed61f05f0c4e9c48f9b692a8c1147 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 14:02:22 -0700 Subject: [PATCH 13/15] style-guide: Make link text in SUMMARY.md match the headings in the linked pages --- src/doc/style-guide/src/SUMMARY.md | 8 ++++---- src/doc/style-guide/src/cargo.md | 2 +- src/doc/style-guide/src/statements.md | 2 ++ 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/src/doc/style-guide/src/SUMMARY.md b/src/doc/style-guide/src/SUMMARY.md index 004692fa6a22b..59fe9fdc6694a 100644 --- a/src/doc/style-guide/src/SUMMARY.md +++ b/src/doc/style-guide/src/SUMMARY.md @@ -2,10 +2,10 @@ [Introduction](README.md) -- [Module-level items](items.md) +- [Items](items.md) - [Statements](statements.md) - [Expressions](expressions.md) -- [Types](types.md) -- [Non-formatting conventions](advice.md) +- [Types and Bounds](types.md) +- [Other style advice](advice.md) - [`Cargo.toml` conventions](cargo.md) -- [Principles used for deciding these guidelines](principles.md) +- [Guiding principles and rationale](principles.md) diff --git a/src/doc/style-guide/src/cargo.md b/src/doc/style-guide/src/cargo.md index 5e6a62a7fd284..d3b67ae45825d 100644 --- a/src/doc/style-guide/src/cargo.md +++ b/src/doc/style-guide/src/cargo.md @@ -1,4 +1,4 @@ -# Cargo.toml conventions +# `Cargo.toml` conventions ## Formatting conventions diff --git a/src/doc/style-guide/src/statements.md b/src/doc/style-guide/src/statements.md index abb6b492b9121..62a5a032f072e 100644 --- a/src/doc/style-guide/src/statements.md +++ b/src/doc/style-guide/src/statements.md @@ -1,3 +1,5 @@ +## Statements + ### Let statements There should be spaces after the `:` and on both sides of the `=` (if they are From f972e09f76e5d5557a56026b4ffa78eb76df6564 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 14:06:15 -0700 Subject: [PATCH 14/15] style-guide: Define what an item is --- src/doc/style-guide/src/items.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md index 8a0954f53430e..1e0e60248bfbd 100644 --- a/src/doc/style-guide/src/items.md +++ b/src/doc/style-guide/src/items.md @@ -1,5 +1,10 @@ ## Items +Items consist of the set of things permitted at the top level of a module. +However, Rust also allows some items to appear within some other types of +items, such as within a function. The same formatting conventions apply whether +an item appears at module level or within another item. + `extern crate` statements must be first in a file. They must be ordered alphabetically. From fcc23a3bfd827b5c587e4899a6fe6b92d72c048e Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 22 Jun 2023 12:50:04 -0700 Subject: [PATCH 15/15] style-guide: Avoid referring to the style team in the past tense We live! --- src/doc/style-guide/src/principles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/style-guide/src/principles.md b/src/doc/style-guide/src/principles.md index bbf6d76d4216e..d548693e39ed0 100644 --- a/src/doc/style-guide/src/principles.md +++ b/src/doc/style-guide/src/principles.md @@ -1,7 +1,7 @@ # Guiding principles and rationale -When deciding on style guidelines, the style team tried to be guided by the -following principles (in rough priority order): +When deciding on style guidelines, the style team follows these guiding +principles (in rough priority order): * readability - scan-ability