Stop suggesting alphabetic arrangement between different types of items (structs vs funcs vs mods etc)

[amab8901]

Summary

I think that arbitrary_source_item_ordering should stop comparing names that belong to different types of items.

For example I want main() to always be at the top, and I want mod tests {} to always be at the bottom. But if I have an function called send_to_database(), this lint will send me an annoying suggestion to "put mod tests {} before send_to_database(). Yet turning off this lint entirely isn't desirable either because it's valuable to have items of the same type arranged alphabetically (for example fields in a struct).

Lint Name

arbitrary_source_item_ordering

Reproducer

I tried this code:

fn main() {
    let structy = Structy::default();
    let _field1 = structy.field1();
    let _field_one = Structy::field1(&structy);
}

#[derive(Default)]
pub(crate) struct Structy {
    field1: String,
}

impl Structy {
    pub(crate) fn field1(&self) -> &String {
        &self.field1
    }
}

I saw this happen:

incorrect ordering of items (module item groupings specify another order)

I expected to see this happen:
silence

Version

rustc 1.87.0 (17067e9ac 2025-05-09)
binary: rustc
commit-hash: 17067e9ac6d7ecb70e50f92c1944e545188d2359
commit-date: 2025-05-09
host: x86_64-unknown-linux-gnu
release: 1.87.0
LLVM version: 20.1.1

Additional Labels

No response

[sesgoe]

Hey @amab8901,

I took a look at this earlier today just out of curiosity, and I think arbitrary_source_item_ordering is doing what it's supposed to, and this might be a misunderstanding of the config.

If you supply this config in your clippy.toml at project root:

trait-assoc-item-kinds-order = ["const", "type", "fn"]
source-item-ordering = ["enum", "impl", "module", "struct", "trait"]
module-item-order-groupings = [
    ["modules", ["extern_crate", "mod", "foreign_mod"]],
    ["use", ["use"]],
    ["macros", ["macro"]],
    ["global_asm", ["global_asm"]],
    ["UPPER_SNAKE_CASE", ["static", "const"]],
    ["lower_snake_case", ["fn"]], # 👈 moved this line up
    ["PascalCase", ["ty_alias", "enum", "struct", "union", "trait", "trait_alias", "impl"]] # 👈 moved this line down
]
module-items-ordered-within-groupings = "none"

Your given example with the Structy structs no longer throws a clippy warning. The important thing is defining fns to be sorted before structs.

---

Your second, abruptly mentioned example (involving mod test and send_to_database()) in the paragraph above your reproduction code, however, sparks what seems like a worthy distinction/discussion.

In Rust source code, mod statements can be written two main ways that I know of:

mod my_module; which specifies that there is an eternal my_module folder or my_module.rs file that has stuff in it that also needs to be compiled/linked/etc

and then there are inline mod definitions like mod test { } that are usually rather different, and frequently just inlined unit tests.

It seems worth considering to me if it's possible to differentiate between mod my_mod and mod with_braces {} for the purposes of sorting/arrangement with arbitrary_source_item_ordering.

Because I can see a world where I want a source file to look like this:

mod my_mod;

fn main() {
  // do stuff
}

fn helper_functions() {
  // do helper stuff
}

mod test {
  // unit tests go here
}

And that would involve creating a distinction between mod my_mod and mod with_braces {}.

Unfortunately, this lint does not have specific support for handling mod test in any special way, as mentioned in its lovely doc comment:

    /// #### Module Tests
    ///
    /// This lint does not implement detection of module tests (or other feature
    /// dependent elements for that matter). To lint the location of mod tests,
    /// the lint `items_after_test_module` can be used instead.

I haven't quite dug into what that might look like, but in general, I support your endeavors.

---

So, as far as I can tell, your issue (as currently titled) is not actually an issue at all. The arbitrary_source_item_ordering lint does not appear to be confusing alphabetic arrangements of different types of items. The error you see:

incorrect ordering of items (module item groupings specify another order)

Indicates that this is the case. It does not mention alphabetic sorting. I think this issue can be closed as-is, but the above point is still certainly worth opening a new issue for / discussing in general. It's one of those "I didn't know I wanted that!" kind of finds for me.

[sesgoe]

As an addendum that I just found:

#14585

If there is a #[cfg(test)] attribute on a particular mod definition in a file, it will be ignored for sorting reasons. So, what you are asking for is theoretically already possible (except for maybe requiring a specific function name be sorted at the top, like main).

The distinction I mentioned remains, however. I can see that the enum definition includes support for both Mod and ForeignMod, but a ForeignMod is just the extern keyword, and is not related to the different kinds of mod definitions that can exist.