style-guide: clean up "must"/"should"/"may"#113380
Merged
bors merged 9 commits intorust-lang:masterfrom Jul 21, 2023
Merged
Conversation
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Avoid using "should" or "may" for required parts of the default style.
The style guide inconsistently used language like "there should be a space" or
"it should be on its own line", or "may be written on a single line", for
things that are required components of the default Rust style. "should" and
especially "may" come across as optional. While the style guide overall now has
a statement at the top that the default style itself is a recommendation, the
definition of the default style should not be ambiguous about what's part of
the default style.
Rewrite language in the style guide to only use "should" and "may" and similar
for truly optional components of the style (e.g. things a tool cannot or should
not enforce in its default configuration).
In their place, either use "must", or rewrite in imperative style ("put a
space", "start it on the same line"). The latter also substantially reduces the
use of passive voice.
Looking for "should"s also flagged some recommendations the style guide made
for configurability of tools (e.g. a tool "should" have a given configuration
option). I've removed those recommendations, per discussion with the style
team; it's not the domain of the style guide to make such recommendations, only
to define the default Rust style.
In the process of making this change, I also fixed a typo, fixed a text structure
issue, fixed an example that didn't match the Rust style (missing a trailing
comma), and added an additional example for clarity. (Those changes would have
conflicted with this one.) Those changes appear in separate commits.
These are all purely editorial changes, and do not affect the semantic
definition of the Rust style.