Skip to content

Amend style guide section for formatting where clauses in type aliases #114901

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 27, 2023
Merged

Amend style guide section for formatting where clauses in type aliases #114901

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
85254c9
bugfix: reflect how rustfmt formats type aliases
compiler-errors Aug 16, 2023
f707b9c
Describe how to format trailing where clauses
compiler-errors Aug 16, 2023
2ff14b0
Remove opinions from style guide about where clauses in type alias items
compiler-errors Aug 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 28 additions & 5 deletions src/doc/style-guide/src/items.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -367,26 +367,49 @@ where
## Type aliases

Keep type aliases on one line when they fit. If necessary to break the line, do
so after the `=`, and block-indent the right-hand side:
so before the `=`, and block-indent the right-hand side:

```rust
pub type Foo = Bar<T>;

// If multi-line is required
type VeryLongType<T, U: SomeBound> =
AnEvenLongerType<T, U, Foo<T>>;
type VeryLongType<T, U: SomeBound>
= AnEvenLongerType<T, U, Foo<T>>;
```

Where possible avoid `where` clauses and keep type constraints inline. Where
that is not possible split the line before and after the `where` clause (and
split the `where` clause as normal), e.g.,
that is not possible, prefer a trailing `where` clause over one that precedes
Copy link
Member

@calebcartwright calebcartwright Aug 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Part of what was also done in #113380 was removing some (but not all) usages of "prefer".

My interpretation of this is that this one is indeed intentional, targeted more at the human developer, aware that the clause can go in either/both position, and trying to encourage the latter because we feel like the style guide has to provide rules for both positions?

(edits: repeated typos, oh my)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should use "prefer" in any case where we expect a tool to do any kind of enforcement. But in this case, I don't think we expect a tool to convert between the two where positions?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tools should not convert. Prefix WC is an error in the positions where it matters, so maybe we don't even need to tell them about preference at all. Happy to reword or remove.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tools, including rustfmt, certainly could and it's probably worth noting that during some of the earlier rfc and implementation discussions that was explicitly suggested/requested.

I know there's differing philosophies around the should part of the question though

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well given that I'm probably in the position of having the least context and caring the least about this specific wording, one of y'all are free to suggest a rewording here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think (A) is the best way to go here, or to just remove the wording altogether and leave it up to the language to enforce what to do with where clause placement. The guide could perhaps just explain what to do in the cases of prefix, suffix, and prefix+suffix where clauses and take no opinions.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, I don't have objections to either (A) or (C) in isolation; however, I'd object to doing (C) if we're not waiting for a new style edition, because that would produce more churn.

As for (B), I think the style guide should be providing documentation for how to format any language construct that exists in the language. If something hasn't been removed from the language, we should document how to handle it (even if the handling is (C), "convert it to something else"). We shouldn't leave things undocumented/implied.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, there's a bigger overriding consideration here. @compiler-errors just pointed out to me that the two locations have a semantic difference: where clauses before the = aren't enforced, while where clauses in the later position (which for item-level type aliases are currently only allowed in nightly) are enforced. So we should never move one to the other as a matter of mere style.

That means we should just describe both positions, and state that since there's a semantic difference between them, the Rust style does not express a preference or suggest moving constraints from one position to the other.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will update, which should resolve this convo. Hopefully after that we can kick off an FCP?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup, agreed with moving ahead

As for (B), I think the style guide should be providing documentation for how to format any language construct that exists in the language

I know this is more a framing/way of thinking moving forward, but I wanted to add before I forget that one potential area of nuance to this is to what degree, if any, the guide must account for formatters that operate prior to the AST validation stage (as rustfmt does), and things that aren't technically valid/exist in the language but which do pass the initial parsing phase

the type. Split the line before and after a trailing `where` clause (and split
the `where` clause as normal) and indent before the `=` and type, e.g.,

```rust
type VeryLongType<T, U>
= AnEvenLongerType<T, U, Foo<T>>
where
T: U::AnAssociatedType,
U: SomeBound;
```

When there is a `where` clause before the type, format it normally, and break
after the last clause. Do not indent before the `=` to leave it visually
distinct from the indented clauses.

```
type WithPrecedingWC<T, U>
where
T: U::AnAssociatedType,
U: SomeBound,
= AnEvenLongerType<T, U, Foo<T>>;

// Or with both a preceding and trailing where clause.
type WithPrecedingWC<T, U>
where
T: U::AnAssociatedType,
U: SomeBound,
= AnEvenLongerType<T, U, Foo<T>>
where
T: U::AnAssociatedType2,
U: SomeBound2;
```

## Associated types
Expand Down