# rust-best-practices

**Repository Path**: mirrors_apollographql/rust-best-practices

## Basic Information

- **Project Name**: rust-best-practices
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-23
- **Last Updated**: 2025-09-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Rust Programming Best Practices Handbook

This book is complementary to the Rust Official API Guidelines:
* [Rust Official API Guidelines](https://rust-lang.github.io/api-guidelines/about.html)

As another source of reference, the Rust Analyzer Style Guide should also be used:
* [Rust Analyzer Style Guide](https://rust-analyzer.github.io/book/contributing/style.html)

## Summary
- [Chapter 1 - Coding Style and Idioms](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_01.md)
    - [Borrowing Over Cloning](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_01.md#11-borrowing-over-cloning)
    - [When to pass by value?](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_01.md#12-when-to-pass-by-value-copy-trait)
    - [Handling Option<T> and Result<T, E>](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_01.md#13-handling-option-and-resultt-e)
    - [Prevent Early Allocation](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_01.md#14-prevent-early-allocation)
    - [Iterator, `.iter` vs `for`](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_01.md#15-iterator-iter-vs-for)
    - [Comments: Context, not Clutter](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_01.md#16-comments-context-not-clutter)
    - [Use Declarations - "imports"](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_01.md#17-use-declarations---imports)
- [Chapter 2 - Clippy and Linting Discipline](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_02.md)
    - [Why care about linting?](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_02.md#21-why-care-about-linting)
    - [Always run `cargo clippy`](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_02.md#22-always-run-cargo-clippy)
    - [Important Clippy Lints to Respect](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_02.md#23-important-clippy-lints-to-respect)
    - [Fix warnings, don't silence them!](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_02.md#24-fix-warnings-dont-silence-them)
    - [Configure workspace/package lints](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_02.md#25-configure-workspacepackage-lints)
- [Chapter 3 - Performance Mindset](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_03.md)
    - [Cargo Flamegraph](/book/chapter_03.md#31-flamegraph)
    - [Avoid Redundant Cloning](/book/chapter_03.md#32-avoid-redundant-cloning)
    - [Stack vs. Heap: Be size-smart!](/book/chapter_03.md#33-stack-vs-heap-be-size-smart)
    - [Iterators and Zero-Cost Abstractions](/book/chapter_03.md#34-iterators-and-zero-cost-abstractions)
- [Chapter 4 - Errors and Results](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_04.md)
    - [Prefer `Result`, avoid panic](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_04.md#41-prefer-result-avoid-panic)
    - [Avoid `unwrap/expect` in Production](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_04.md#42-avoid-unwrapexpect-in-production)
    - [`thiserror` for Crate Level Errors](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_04.md#43-thiserror-for-crate-level-errors)
    - [Reserve `anyhow` for Binaries](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_04.md#44-reserve-anyhow-for-binaries)
    - [Use `?` to Bubble Errors](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_04.md#45-use--to-bubble-errors)
    - [Unit Tests should exercise errors](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_04.md#46-unit-test-should-excercise-errors)
    - [Important Topics](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_04.md#47-important-topics)
- [Chapter 5 - Automated Testing](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_05.md)
    - [Tests as Living Documentation](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_05.md#51-tests-as-living-documentation)
    - [Add Test Examples to your Docs](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_05.md#52-add-test-examples-to-your-docs)
    - [Unit Test vs Integration Tests vs Doc tests](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_05.md#53-unit-test-vs-integration-tests-vs-doc-tests)
    - [How to `assert!`](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_05.md#54-how-to-assert)
    - [Snapshot Testing with `cargo insta`](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_05.md#55-snapshot-testing-with-cargo-insta)
    - [Snapshot Best Practices](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_05.md#56--snapshot-best-practices)
- [Chapter 6 - Generics, Dynamic Dispatch and Static Dispatch](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_06.md)
    - [Generics](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_06.md#61-generics)
    - [Static Dispatch: `impl Trait` or `<T: Trait>`](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_06.md#62-static-dispatch-impl-trait-or-t-trait)
    - [Dynamic Dispatch: `dyn Trait`](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_06.md#63-dynamic-dispatch-dyn-trait)
    - [Trade-off summary](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_06.md#64-trade-off-summary)
    - [Best Practices for Dynamic Dispatch](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_06.md#65-best-practices-for-dynamic-dispatch)
    - [Trait Objects Ergonomics](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_06.md#66--trait-objects-ergonomics)
- [Chapter 7 - Type State Pattern](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_07.md)
    - [What is Type State Pattern?](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_07.md#71-what-is-type-state-pattern)
    - [Why use it?](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_07.md#72-why-use-it)
    - [Simple Example: File State](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_07.md#73-simple-example-file-state)
    - [Real-World Examples](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_07.md#74-real-world-examples)
    - [Pros and Cons](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_07.md#75-pros-and-cons)
- [Chapter 8 - Comments vs Documentation](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_08.md)
    - [Comments vs Documentation: Know the Difference](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_08.md#81-comments-vs-documentation-know-the-difference)
    - [When to use comments](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_08.md#82-when-to-use-comments)
    - [When comments get in the way](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_08.md#83-when-comments-get-in-the-way)
    - [Don't Write Living Documentation (living comments)](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_08.md#84-dont-write-living-documentation-living-comments)
    - [Replace Comments with Code](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_08.md#85-replace-comments-with-code)
    - [`TODO` should become issues](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_08.md#86-todo-should-become-issues)
    - [When to use doc comments](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_08.md#87-when-to-use-doc-comments)
    - [Documentation in Rust: How, When and Why](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_08.md#88-documentation-in-rust-how-when-and-why)
    - [Checklist for Documentation coverage](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_08.md#89-checklist-for-documentation-coverage)
- [Chapter 9 - Understanding Pointers](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_09.md)
    - [Thread Safety](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_09.md#91-thread-safety)
    - [When to use pointers](https://github.com/apollographql/rust-best-practices/blob/main/book/chapter_09.md#92-when-to-use-pointers)
- [Final Notes](https://github.com/apollographql/rust-best-practices/blob/main/book/zz_final_notes.md)