Defining modules in Rust - Deep Dive

Overview - Defining modules

What is it?

In Rust, a module is a way to organize code into separate namespaces. It helps group related functions, structs, and other items together. Modules can be defined inside files or folders, making large programs easier to manage. They control what parts of the code are visible to other parts.

Why it matters

Without modules, all code would be in one big space, causing confusion and name clashes. Modules let programmers split code into clear sections, making it easier to find, fix, and reuse. This organization is crucial for building safe and maintainable Rust programs, especially as they grow.

Where it fits

Before learning modules, you should understand basic Rust syntax, functions, and structs. After modules, you can learn about crates, packages, and how to share code across projects. Modules are a stepping stone to mastering Rust's package system and code reuse.

Mental Model

Core Idea

Modules are like labeled boxes that hold related code, keeping it organized and controlling what is shared outside.

Think of it like...

Imagine a toolbox with separate compartments for screws, nails, and tools. Each compartment keeps things tidy and prevents mixing up items, just like modules keep code organized and separate.

root module
├── submodule1
│   ├── function_a
│   └── struct_a
└── submodule2
    ├── function_b
    └── struct_b

Modules form a tree where each branch holds related code.

Build-Up - 7 Steps

1

Foundation

What is a Rust module?

Concept: Introducing the basic idea of a module as a code container.

In Rust, you create a module using the keyword `mod`. For example: mod kitchen { fn cook() { println!("Cooking food"); } } This code defines a module named `kitchen` that contains a function `cook`.

Result

The code compiles and the `kitchen` module holds the `cook` function inside it.

Understanding that modules group code helps you start organizing your program logically.

2

Foundation

Module visibility basics

Concept: How modules control what code is visible outside them.

By default, items inside a module are private. To let other parts use them, you add `pub`: mod kitchen { pub fn cook() { println!("Cooking food"); } } Now, `cook` can be called from outside `kitchen`.

Result

Trying to call `kitchen::cook()` from outside works only if `cook` is public.

Knowing visibility rules prevents accidental access to internal code and keeps your API clean.

3

Intermediate

Modules in separate files

🤔Before reading on: do you think defining a module in another file requires special syntax or just the same `mod` keyword? Commit to your answer.

Concept: How to split modules into different files for better organization.

Rust lets you put modules in separate files. For example, if you write `mod kitchen;` in `main.rs`, Rust looks for a file named `kitchen.rs` or a folder `kitchen/mod.rs`. This way, you keep code clean and manageable.

Result

The program compiles and runs with the module code loaded from another file.

Understanding file-based modules helps you scale your projects beyond one file.

4

Intermediate

Nested modules and paths

🤔Before reading on: do you think nested modules require repeating `mod` inside each module or just once at the root? Commit to your answer.

Concept: How to create modules inside modules and access their items.

You can define modules inside other modules: mod house { pub mod kitchen { pub fn cook() { println!("Cooking in kitchen"); } } } To call `cook`, use `house::kitchen::cook()`.

Result

Calling `house::kitchen::cook()` prints the cooking message.

Knowing nested modules lets you build a clear hierarchy and avoid name clashes.

5

Intermediate

Using `use` to simplify paths

🤔Before reading on: do you think `use` copies code or just creates shortcuts? Commit to your answer.

Concept: How to bring module items into scope to avoid long names.

The `use` keyword lets you write shorter names: use house::kitchen::cook; fn main() { cook(); } This calls the function without the full path every time.

Result

The program runs and prints the cooking message using the short name.

Understanding `use` improves code readability and reduces repetition.

6

Advanced

Module privacy and crate boundaries

🤔Before reading on: do you think `pub` makes items visible everywhere or only within the crate? Commit to your answer.

Concept: How module visibility works across crates and the role of `pub(crate)` and `pub(super)`.

By default, `pub` items are visible everywhere in the current crate (project). To restrict visibility: - `pub(crate)` makes items visible only inside the crate. - `pub(super)` makes items visible to the parent module. This fine control helps design safe APIs.

Result

Code respects visibility rules, preventing unwanted access from outside modules or crates.

Knowing these visibility levels helps you design clear and safe module boundaries.

7

Expert

How Rust resolves module paths internally

🤔Before reading on: do you think Rust looks for modules only in files or also in folders with special files? Commit to your answer.

Concept: Understanding Rust's module resolution rules and how it finds files and folders for modules.

Rust uses a set of rules: - `mod name;` looks for `name.rs` or `name/mod.rs`. - Nested modules can be inline or in folders. - The compiler builds a tree of modules from these files. This system balances flexibility and convention for organizing code.

Result

Rust compiles code correctly by following these rules, enabling modular project structures.

Understanding this prevents confusion when organizing large projects and debugging module errors.

Under the Hood

Rust modules create namespaces that the compiler uses to organize code items. When compiling, Rust builds a tree structure of modules by reading `mod` declarations and loading corresponding files or inline code. Visibility keywords (`pub`, `pub(crate)`, etc.) control symbol export in this tree. The compiler uses this structure to resolve names and enforce access rules at compile time, ensuring safety and clarity.

Why designed this way?

Rust's module system was designed to balance flexibility and simplicity. Using files and folders as modules fits naturally with the filesystem, making it easy to organize code. Visibility controls prevent accidental misuse of internal code, improving safety. Alternatives like flat namespaces or runtime module loading were rejected to keep compile-time guarantees and performance.

root (crate)
├── mod.rs or main.rs
│   ├── mod kitchen (kitchen.rs or kitchen/mod.rs)
│   │   ├── pub fn cook
│   │   └── mod utensils
│   │       └── pub fn use_knife
│   └── mod living_room
│       └── pub fn relax

Compiler builds this tree to resolve names and visibility.

Myth Busters - 4 Common Misconceptions

Quick: Does `pub` make a function visible outside the crate by default? Commit to yes or no.

Common Belief: Many think `pub` means the function is visible everywhere, including other projects.

Reality: `pub` makes items visible everywhere inside the current crate only. To expose items outside the crate, you must publish the crate as a library and use `pub` to expose the API.

Why it matters: Assuming `pub` exposes code outside the crate can lead to broken APIs and confusion when other projects can't access your code.

Quick: Can you define multiple modules with the same name in different files without conflict? Commit to yes or no.

Common Belief: Some believe module names are global and must be unique across the whole project.

Reality: Module names are scoped by their parent modules. You can have the same module name in different parent modules without conflict.

Why it matters: Misunderstanding this limits how you organize code and can cause unnecessary renaming.

Quick: Does `use` copy the code into your file? Commit to yes or no.

Common Belief: Many think `use` duplicates or imports code physically into the current file.

Reality: `use` only creates a shortcut or alias for a path; it does not copy or move code.

Why it matters: Thinking `use` copies code can lead to confusion about code size and compilation.

Quick: Are inline modules and file modules treated differently by the compiler? Commit to yes or no.

Common Belief: Some believe inline modules and file modules behave differently at runtime or compile time.

Reality: Both inline and file modules are treated the same by the compiler; the difference is only in source organization.

Why it matters: This misconception can cause unnecessary refactoring or confusion about module behavior.

Expert Zone

1

Module privacy rules interact subtly with Rust's macro system, affecting what macros can see and expand.

2

The choice between inline modules and file modules can impact compile times and incremental compilation efficiency.

3

Using `pub(crate)` and `pub(super)` strategically allows fine-grained API design, balancing encapsulation and usability.

When NOT to use

Avoid using deeply nested modules for very small projects where simplicity matters more than organization. Instead, keep code flat. For dynamic plugin systems, Rust's static module system is limiting; consider dynamic loading or trait objects.

Production Patterns

In large Rust projects, modules are organized by feature or domain, often mirroring folder structure. Public APIs expose only necessary modules with `pub`, hiding internals. `use` statements are grouped at the top for clarity. Crates use modules to separate core logic, utilities, and tests cleanly.

Connections

Namespaces in C++

Modules in Rust serve a similar purpose as namespaces in C++ by grouping code and avoiding name clashes.

Understanding Rust modules helps grasp how other languages organize code and manage symbol visibility.

Packages in logistics

Modules are like packages in shipping that group items for easier handling and delivery.

Seeing modules as packages clarifies why grouping and labeling code is essential for managing complexity.

File folders in operating systems

Rust modules map closely to folders and files, just like how OS folders organize documents.

Knowing this connection helps understand why Rust uses filesystem structure for modules.

Common Pitfalls

#1 Trying to access a private function from outside its module.

Wrong approach:

mod kitchen {
fn cook() {}
}

fn main() {
kitchen::cook(); // error: function is private
}

Correct approach:

mod kitchen {
pub fn cook() {}
}

fn main() {
kitchen::cook(); // works
}

Root cause:

Not understanding that functions are private by default inside modules.

#2 Defining a module in a separate file but forgetting to declare it in the parent file.

Wrong approach:

// kitchen.rs
pub fn cook() {}

// main.rs
fn main() {
kitchen::cook(); // error: module not found
}

Correct approach:

// main.rs
mod kitchen;

fn main() {
kitchen::cook(); // works
}

Root cause:

Forgetting that Rust needs `mod` declarations to link files as modules.

#3 Using `use` to import a module but not the items inside it, then trying to call the items directly.

Wrong approach:

use kitchen;

fn main() {
cook(); // error: function not found
}

Correct approach:

use kitchen::cook;

fn main() {
cook(); // works
}

Root cause:

Confusing importing a module with importing its contents.

Key Takeaways

Modules in Rust organize code into named containers that help manage complexity and avoid name conflicts.

By default, module items are private; you must use `pub` to share them outside their module.

Modules can be defined inline or in separate files and folders, following Rust's conventions for file structure.

The `use` keyword creates shortcuts to module items, improving code readability without copying code.

Understanding module visibility and organization is essential for building safe, maintainable, and scalable Rust programs.