Was anyone else confused at first about the purpose of `use` and `mod`?

231 points CocktailPerson

I was looking over the Book again recently, and I was reminded of my difficulty understanding how mod worked, and why use on its own didn't. Building my first multi-file project was an exercise in frustration for a while.

I think part of the issue is that it describes use as "importing names" and mod as "declaring modules." This is a bit backward from other languages, which usually "import" or "include" another file's contents, and "declare" names. The chapter of the book makes sense in retrospect, but the fact that mod is what actually imports another file's code as a module is buried in the phrasing "you can declare new modules ... with mod ... The compiler will look for the module’s code in...."

So, I'm wondering if anyone else had similar difficulty. Perhaps the Book would benefit from a two- or three-sentence paragraph explaining that mod imports/includes a file into the module tree, and use imports names from the module tree into the current namespace, and that you won't be able to use a name before moding the file that contains it into the module tree.