Chapter 5: Clean up your codebase
This introduction motivates cleaning up the growing web-service codebase and describes Rust’s documentation, linting, and formatting support.
After this chapter you will be able to
- Main file responsibilities. Explain why the growing main.rs needs cleanup and what role it should have instead.
- Generated and tested documentation. Explain how Rust’s built-in commenting system supports code documentation.
- Linting and formatting tools. Describe the roles of Clippy and Cargo in cleaning up the codebase.
- Logical code organization. Explain why a growing application benefits from grouping logical components into separate files and folders, while a small, stable mock server may work well in main.rs.
- Binary and library crates. Distinguish binary crates from library crates by their outputs and purposes, and identify the associated main.rs and lib.rs files.
- Error handling module. Describe how a named Rust module groups related code and why the example groups error handling together.
- Module scope and imports. Explain why the error module needs its own imports, using Warp's Reject trait as an example.
- Module paths and visibility. Explain how code outside the error module accesses its Error enum and return_error function after they are moved.
- Module tree and visibility. Describe how the example connects sibling files and folder modules to the module tree and makes folder contents available.
- Module declaration and imports. Distinguish declaring a module with mod from accessing its functionality with use, and describe the example's crate-relative import.
- Sub-crate selection tradeoffs. Explain when a sub-crate may be preferable to files or folders, and what workflow costs it can introduce.
- Local error library extraction. Describe how the error module is moved into a local library and connected back to the application.
- Built-in documentation generation. Explain how Rust and Cargo provide documentation even when a codebase has no comments.
- Public and private comments. Distinguish public comments from private comments and describe how Markdown can enrich doc comments.
- Documentation comment forms. Distinguish Rust’s doc-comment forms from ordinary unpublished comments and describe where the doc comments apply.
- Useful documentation content. Describe the recommended content and placement of doc comments for functionality and struct values, and why those comments help.
- Cargo documentation generation. Explain how Cargo generates and opens local documentation and what happens to documentation when a project is published to crates.io.
- Documented code examples. Describe how to include an example in a doc comment and view it in generated documentation.
- Testing documentation examples. Explain how tests help keep code examples current and distinguish the library and binary caveat described in this section.
- Standard Rust Tooling. Explain how Clippy and Rustfmt help address the difficulty of standardizing code-quality tooling across projects and teams.
- Clippy installation and configuration. Describe how to install Clippy and where to configure its linting rules in a project.
- Clippy warning review workflow. Trace the example of running Clippy, interpreting its warning, changing the code, and checking it again.
- Rustfmt formatting and configuration. Explain how Rustfmt formats a project using standard settings and how its formatting options can be adjusted.
What it builds on
- POST, PUT, and DELETE questions (chapter 4) · The route handlers added to the Q&A application.
- Returning custom errors (chapter 4) · The application's custom error handling.
Section by section
Introduction
This introduction motivates cleaning up the growing web-service codebase and describes Rust’s documentation, linting, and formatting support.
- Main file responsibilities: Explain why the growing main.rs needs cleanup and what role it should have instead.
Why it matters: A small coordinating main file makes the application’s responsibilities easier to separate. - Generated and tested documentation: Explain how Rust’s built-in commenting system supports code documentation.
Why it matters: Generated documentation and tested examples help readers rely on explanations of the code. - Linting and formatting tools: Describe the roles of Clippy and Cargo in cleaning up the codebase.
Why it matters: Linting and formatting help make code more consistent and highlight potential improvements.
Key terms: main.rs, route handler, commenting system, code documentation, Clippy, linter, Cargo, autoformat
5.1 Modularizing your code
This section explains why to organize a growing Rust application into logical units and distinguishes binary crates from library crates.
- Logical code organization: Explain why a growing application benefits from grouping logical components into separate files and folders, while a small, stable mock server may work well in main.rs.
Why it matters: Organizing code by logical component makes a growing project easier to work on and maintain. - Binary and library crates: Distinguish binary crates from library crates by their outputs and purposes, and identify the associated main.rs and lib.rs files.
Why it matters: The distinction helps you decide what starts the application and what exposes reusable functionality.
Key terms: logical components, main.rs, folders and files, binary crate, library crate, lib.rs, --lib
5.1.1 Using Rust’s built-in mod system
This section groups error handling into a Rust module and resolves the resulting scope, path, and visibility errors.
- Error handling module: Describe how a named Rust module groups related code and why the example groups error handling together.
Why it matters: Grouping related code makes its responsibilities and dependencies easier to see. - Module scope and imports: Explain why the error module needs its own imports, using Warp's Reject trait as an example.
Why it matters: Recognizing separate scopes helps explain missing-name errors after moving code into a module. - Module paths and visibility: Explain how code outside the error module accesses its Error enum and return_error function after they are moved.
Why it matters: A correct path and public visibility are both needed for the rest of the application to use the moved error-handling code.
Key terms: mod, module, snake_case, error module, scope, import, Reject, error::Error, error::return_error, pub
5.1.2 Practical folder structure for different use cases
This section moves code out of main.rs and shows how to connect and access modules organized as files and folders.
- File and folder choices: Describe how the complexity of grouped code influences the choice between a single file and a folder of files.
Why it matters: This choice helps keep related code manageable as the application grows. - Redundant nested module scope: Explain why the inline error module declaration is removed after its contents move to error.rs.
Why it matters: Avoiding an unnecessary nested module keeps paths to the error types simpler. - Module tree and visibility: Describe how the example connects sibling files and folder modules to the module tree and makes folder contents available.
Why it matters: The module tree makes the extracted code available where the application needs it. - Module declaration and imports: Distinguish declaring a module with mod from accessing its functionality with use, and describe the example's crate-relative import.
Why it matters: Declaring a module and importing its functionality are separate steps when code is split across files.
Key terms: main.rs, error.rs, routes, mod {}, scope, error::, mod, mod.rs, pub mod, private
5.1.3 Creating libraries and sub-crates
This section explains when to extract code into a library and demonstrates moving application error handling into a local sub-crate.
- Sub-crate selection tradeoffs: Explain when a sub-crate may be preferable to files or folders, and what workflow costs it can introduce.
Why it matters: Choosing the right boundary avoids unnecessary workflow complexity while making reusable code easier to share. - Local error library extraction: Describe how the error module is moved into a local library and connected back to the application.
Why it matters: This shows how to keep extracted code usable without relying on the old module location. - Standalone library versioning: Explain why an extracted library might eventually be maintained as a standalone library.
Why it matters: Separating stable code can make it available independently without tying it to the larger codebase's version increases.
Key terms: sub-crate, folders, separate files, Git flow, library, lib.rs, Cargo.toml, local path, handle-errors, Warp
5.2 Documenting your code
This section introduces Rust’s built-in documentation system, its treatment of comments, and the value of documenting applications.
- Built-in documentation generation: Explain how Rust and Cargo provide documentation even when a codebase has no comments.
Why it matters: Rust can provide a useful documentation starting point without requiring every item to have a comment. - Public and private comments: Distinguish public comments from private comments and describe how Markdown can enrich doc comments.
Why it matters: The kind of comment determines whether readers of the documentation see it, and Markdown helps make doc comments readable. - Application documentation value: Explain why comments are useful in applications as well as libraries.
Why it matters: Comments can make an application easier to understand when someone returns to it months or years later.
Key terms: documentation, Cargo, traits, functions, public comments, private comments, doc comments, Markdown, comments
5.2.1 Using doc comments and private comments
This section distinguishes Rust documentation comments from unpublished comments, recommends what to document, and shows how to generate and browse the documentation.
- Documentation comment forms: Distinguish Rust’s doc-comment forms from ordinary unpublished comments and describe where the doc comments apply.
Why it matters: Choosing the right comment form determines whether it contributes to published documentation. - Useful documentation content: Describe the recommended content and placement of doc comments for functionality and struct values, and why those comments help.
Why it matters: Useful doc comments make both the code and its generated documentation easier to revisit. - Cargo documentation generation: Explain how Cargo generates and opens local documentation and what happens to documentation when a project is published to crates.io.
Why it matters: Generating documentation lets you navigate the project locally and understand how published crate docs appear.
Key terms: doc comments, one-line doc comment, block doc comment, business perspective, examples section, cargo doc, cargo doc --open, docs.rs, crates.io
5.2.2 Adding code in your comments
This section explains how to add and generate documentation with Rust code examples and how testing those examples helps keep them current.
- Documented code examples: Describe how to include an example in a doc comment and view it in generated documentation.
Why it matters: A rendered example helps readers see how to use a feature. - Testing documentation examples: Explain how tests help keep code examples current and distinguish the library and binary caveat described in this section.
Why it matters: Testing examples can expose documentation that no longer matches the code.
Key terms: doc comments, Markdown, cargo doc --open, syntax highlighting, tests, library, binary
5.3 Linting and formatting your codebase
The section introduces Rust’s standard code-quality tools and their value for consistent tooling.
- Standard Rust Tooling: Explain how Clippy and Rustfmt help address the difficulty of standardizing code-quality tooling across projects and teams.
Why it matters: Shared, officially supported tools can make consistent code-quality practices easier across projects and teams.
Key terms: Clippy, Rustfmt, linting, standard tools
5.3.1 Installing and using Clippy
This section shows how to configure and run Clippy, use its warnings to improve code, and select collections of linting rules.
- Clippy installation and configuration: Describe how to install Clippy and where to configure its linting rules in a project.
Why it matters: This gives you a way to set up linting for your Rust project. - Clippy warning review workflow: Trace the example of running Clippy, interpreting its warning, changing the code, and checking it again.
Why it matters: The workflow turns lint warnings into concrete code improvements you can verify. - Lint rule collections: Explain why Clippy offers collections of linting rules and distinguish examples of those collections.
Why it matters: Rule collections let you choose broader linting guidance without selecting every rule individually.
Key terms: Clippy, rustup, clippy.toml, .clippy.toml, main.rs, lib.rs, cargo clippy, cargo clean, is_empty, linting rule
5.3.2 Formatting your code with Rustfmt
This section introduces Rustfmt for automatically formatting a Rust project and configuring its formatting rules.
- Rustfmt formatting and configuration: Explain how Rustfmt formats a project using standard settings and how its formatting options can be adjusted.
Why it matters: Rustfmt helps keep a project’s formatting consistent while allowing its rules to be customized.
Key terms: Rustfmt, rustfmt.toml, Cargo.toml, standard format settings
5.4 Summary
Where this is used later
- Extract the configuration of the web server into a new module (chapter 10) · Uses the idea of separating a logical component into its own module.
- Splitting up the codebase into a lib.rs and a binary (chapter 11) · Uses the distinction when splitting the codebase into a library and a binary.
- Refactoring the add_question route handler (chapter 8) · Rust's module declaration system.
- Creating the user concept (chapter 9) · Rust's module system and exposing modules
Concepts explained in this chapter
- mod keywordThe mod keyword in Rust declares a module and identifies its source location.
- doc commentA Rust doc comment is a comment interpreted as documentation and used to generate documentation for code.
- library crateA library crate is a Rust crate that provides functionality through a public interface rather than creating an executable.
- cargo clippycargo clippy is a Cargo command that runs Clippy on a Rust package.
- documentationSoftware documentation is written information describing software, its behavior, or how to use it.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
