[Wilfred]

> Rust's users find the module system even more difficult than the borrow checker. I've tried to figure out why, and figure out how to explain it better, for years now.

The module system in Rust is conceptually huge, and I feel it needs a 'Rust modules: the good parts' resource to guide people.

(1) There are five different ways to use `pub`. That's pretty overwhelming, and in practice I almost never see `pub(in foo)` used.

(2) It's possible to have nested modules in a single file, or across multiple files. I almost never see modules with braces, except `mod tests`.

(3) It's possible to have either foo.rs or foo/mod.rs. It's also possible to have both foo.rs and foo/bar.rs, which feels inconsistent.

(4) `use` order doesn't matter, which can make imports hard to reason about. Here's a silly example:

use foo::bar; use bar::foo;

(Huge fan of your writing, by the way!)

[steveklabnik]

Full agree with 1, I do use 2 depending (if I'm making a tree of modules for organization, and a module only contains imports of other modules, I'll use the curly brace form to save the need of making a file), and I'm not sure why 4 makes it harder? Wouldn't it be more confusing if order mattered? maybe I need to see a full example :)

Thank you!

[Wilfred]

In `use foo::bar; use bar::foo;`, am I importing an external crate called foo that has a submodule bar::foo, or vice versa?

This bit me when trying to write a static analysis tool for Rust that finds missing imports: you essentially need to loop over imports repeatedly until you reach a fixpoint. Maybe it bites users rarely in practice.