new lint: `source_item_ordering` #13376

decryphe · 2024-09-10T09:03:04Z

changelog: [source_item_ordering]: Introduced a new restriction lint that checks the ordering of items in Modules, Enums, Structs, Impls and Traits.

From the written documentation:

Why restrict this?
Keeping a consistent ordering throughout the codebase helps with working as a team, and possibly improves maintainability of the codebase. The idea is that by defining a consistent and enforceable rule for how source files are structured, less time will be wasted during reviews on a topic that is (under most circumstances) not relevant to the logic implemented in the code. Sometimes this will be referred to as "bike-shedding".

Keep in mind, that ordering source code alphabetically can lead to reduced performance in cases where the most commonly used enum variant isn't the first entry anymore, and similar optimizations that can reduce branch misses, cache locality and such. Either don't use this lint if that's relevant, or disable the lint in modules or items specifically where it matters. Other solutions can be to use profile guided optimization (PGO), or other advanced optimization methods.

I tried to build it as configurable as possible, as such a highly opinionated lint should be adjustable to personal opinions.

I'm open to any input and will be available both here and on the zulip for communication. In the meantime I'll be testing this lint against my own code-bases, which I've (manually) kept ordered with the default config, to see how well it works in practice.

And lastly, a big thanks to the community for making clippy the best linter there is!

rustbot · 2024-09-10T09:03:09Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @llogiq (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

@rustbot author: the review is finished, PR author should check the comments and take action accordingly
@rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

book/src/lint_configuration.md

clippy_lints/src/arbitrary_source_item_ordering.rs

llogiq

The big open question is around macro-generated code. Otherwise, apart from a few small doc improvements, this looks good.

clippy_lints/src/arbitrary_source_item_ordering.rs

llogiq · 2024-09-20T20:36:49Z

clippy_lints/src/arbitrary_source_item_ordering.rs

+    /// implemented in the code. Sometimes this will be referred to as
+    /// "bike-shedding".
+    ///
+    /// Keep in mind, that ordering source code alphabetically can lead to


This should be under a # Known problems header.

We also might want to add that the lint doesn't supply suggestions because it's quite hard to produce them in a correct way.

Moved it down to the (now renamed) chapter "Known Problems". Is there a standard way to write this?

Ctrl+F "# Known" yields different ways to write this: "Known problems", "Known Problems", "Known issues"

llogiq · 2024-09-20T20:37:49Z

tests/ui/arbitrary_source_item_ordering.rs

+    const B: i8 = 1;
+
+    const A: i8 = 0;
+}


I'd like to see some macro-generated items. I'm open to debate whether the lint should apply to them.

I've updated the uitests to contain some derive macros. What other things should be tested?
I also added a uitest that passes the ordering lint and produces no output.

Also, note that I've added ordering for trait impls on the module level.
I will add at least a test where I reconfigure item placement of trait impls into its own section, such that it's certainly possible to split trait defs and trait impls. The default groups all CamelCase items, including impls, but I can see why somebody would like to split this category up.

Note: I've added a bunch of test cases, including modified configurations.

Turns out that it can't reasonably be applied to macro-generated items, there's a ton of things in a real codebase that generates items. Using the in_external_macro() function from clippy_utils to filter items yields a decent behaviour in a real code-base.
Also, turns out we do adhere surprisingly well to our own convention, even though we do so manually. Some typos and forgotten things, but nothing majorly wrong in our source file ordering. :-)

I believe this is now in a reviewable state and should work as advertised.

llogiq · 2024-09-21T07:22:16Z

@rustbot author

bors · 2024-09-22T14:36:15Z

☔ The latest upstream changes (presumably #13322) made this pull request unmergeable. Please resolve the merge conflicts.

decryphe · 2024-10-01T08:50:45Z

I'd like to discuss whether or not I should implement another loop before generating lint output that determines the actual location where a snippet should be placed.
Considering the kind-of-weird looking output asking for placement of items before derive macro entries, it's probably worthwhile to do now.

bors · 2024-10-13T07:49:33Z

☔ The latest upstream changes (presumably #13334) made this pull request unmergeable. Please resolve the merge conflicts.

bors · 2024-10-15T16:50:54Z

☔ The latest upstream changes (presumably #13395) made this pull request unmergeable. Please resolve the merge conflicts.

llogiq · 2024-10-27T10:09:33Z

Sorry you had to wait so long, but personal matters left me little time to review this rather large change.

I'd like to check if the clippy_version is still right and this needs a rebase (and feel free to squash), otherwise r=me.

llogiq · 2024-10-29T21:00:17Z

clippy_lints/src/arbitrary_source_item_ordering.rs

+    ///
+    /// [cargo-pgo]: https://github.com/Kobzol/cargo-pgo/blob/main/README.md
+    ///
+    #[clippy::version = "1.81.0"]


Suggested change

#[clippy::version = "1.81.0"]

#[clippy::version = "1.82.0"]

rustbot assigned llogiq Sep 10, 2024

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties label Sep 10, 2024

decryphe force-pushed the source-ordering branch from a1e3223 to 173dd5e Compare September 10, 2024 09:31

alex-semenyuk reviewed Sep 10, 2024

View reviewed changes

book/src/lint_configuration.md Outdated Show resolved Hide resolved

PatchMixolydic reviewed Sep 20, 2024

View reviewed changes

clippy_lints/src/arbitrary_source_item_ordering.rs Outdated Show resolved Hide resolved

llogiq approved these changes Sep 20, 2024

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action from the author. (Use `@rustbot ready` to update this status) and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties labels Sep 21, 2024

decryphe force-pushed the source-ordering branch 2 times, most recently from 3953233 to b46da06 Compare September 27, 2024 14:42

decryphe force-pushed the source-ordering branch 3 times, most recently from 1aa0157 to 8af8a22 Compare October 11, 2024 17:08

decryphe force-pushed the source-ordering branch from 8af8a22 to 72fccdf Compare October 14, 2024 09:17

decryphe force-pushed the source-ordering branch from 1239c30 to 1731ac9 Compare October 29, 2024 10:37

llogiq reviewed Oct 29, 2024

View reviewed changes

decryphe force-pushed the source-ordering branch from 1731ac9 to 97a3b24 Compare October 30, 2024 09:02

new lint: source_item_ordering

f7ab2c9

decryphe force-pushed the source-ordering branch from 97a3b24 to f7ab2c9 Compare October 30, 2024 09:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

new lint: `source_item_ordering` #13376

new lint: `source_item_ordering` #13376

decryphe commented Sep 10, 2024

rustbot commented Sep 10, 2024

llogiq left a comment

llogiq Sep 20, 2024

decryphe Sep 27, 2024

llogiq Sep 20, 2024

decryphe Oct 1, 2024

decryphe Oct 1, 2024

decryphe Oct 11, 2024

decryphe Oct 14, 2024

llogiq commented Sep 21, 2024

bors commented Sep 22, 2024

decryphe commented Oct 1, 2024

bors commented Oct 13, 2024

bors commented Oct 15, 2024

llogiq commented Oct 27, 2024

llogiq Oct 29, 2024

decryphe Oct 30, 2024

new lint: source_item_ordering #13376

Are you sure you want to change the base?

new lint: source_item_ordering #13376

Conversation

decryphe commented Sep 10, 2024

rustbot commented Sep 10, 2024

llogiq left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

llogiq commented Sep 21, 2024

bors commented Sep 22, 2024

decryphe commented Oct 1, 2024

bors commented Oct 13, 2024

bors commented Oct 15, 2024

llogiq commented Oct 27, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

new lint: `source_item_ordering` #13376

new lint: `source_item_ordering` #13376