Skip to content

style-guide: clean up "must"/"should"/"may"#113380

Merged
bors merged 9 commits intorust-lang:masterfrom
joshtriplett:style-guide-cleanup-must-should-may
Jul 21, 2023
Merged

style-guide: clean up "must"/"should"/"may"#113380
bors merged 9 commits intorust-lang:masterfrom
joshtriplett:style-guide-cleanup-must-should-may

Conversation

@joshtriplett
Copy link
Copy Markdown
Member

@joshtriplett joshtriplett commented Jul 5, 2023

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.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-style Relevant to the style team, which will review and decide on the PR/issue.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants