Rust Best Practices
Apply these guidelines when writing or reviewing Rust code. Based on Apollo GraphQL's Rust Best Practices Handbook.
Best Practices Reference
Before reviewing, familiarize yourself with Apollo's Rust best practices. Read ALL relevant chapters in the same turn in parallel. Reference these files when providing feedback:
- Chapter 1 - Coding Styles and Idioms: Borrowing vs cloning, Copy trait, Option/Result handling, iterators, comments
- Chapter 2 - Clippy and Linting: Clippy configuration, important lints, workspace lint setup
- Chapter 3 - Performance Mindset: Profiling, avoiding redundant clones, stack vs heap, zero-cost abstractions
- Chapter 4 - Error Handling: Result vs panic, thiserror vs anyhow, error hierarchies
- Chapter 5 - Automated Testing: Test naming, one assertion per test, snapshot testing
- Chapter 6 - Generics and Dispatch: Static vs dynamic dispatch, trait objects
- Chapter 7 - Type State Pattern: Compile-time state safety, when to use it
- Chapter 8 - Comments vs Documentation: When to comment, doc comments, rustdoc
- Chapter 9 - Understanding Pointers: Thread safety, Send/Sync, pointer types
Quick Reference
Borrowing & Ownership
- Prefer
&T over .clone() unless ownership transfer is required
- Use
&str over String, &[T] over Vec<T> in function parameters
- Small
Copy types (≤24 bytes) can be passed by value
- Use
Cow<'_, T> when ownership is ambiguous
Error Handling
- Return
Result<T, E> for fallible operations; avoid panic! in production
- Never use
unwrap()/expect() outside tests
- Use
thiserror for library errors, anyhow for binaries only
- Prefer
? operator over match chains for error propagation
Performance
- Always benchmark with
--release flag
- Run
cargo clippy -- -D clippy::perf for performance hints
- Avoid cloning in loops; use
.iter() instead of .into_iter() for Copy types
- Prefer iterators over manual loops; avoid intermediate
.collect() calls
Linting
Run regularly: cargo clippy --all-targets --all-features --locked -- -D warnings
Key lints to watch:
redundant_clone - unnecessary cloning
large_enum_variant - oversized variants (consider boxing)
needless_collect - premature collection
Use #[expect(clippy::lint)] over #[allow(...)] with justification comment.
Testing
- Name tests descriptively:
process_should_return_error_when_input_empty()
- One assertion per test when possible
- Use doc tests (
///) for public API examples
- Consider
cargo insta for snapshot testing generated output
Generics & Dispatch
- Prefer generics (static dispatch) for performance-critical code
- Use
dyn Trait only when heterogeneous collections are needed
- Box at API boundaries, not internally
Type State Pattern
Encode valid states in the type system to catch invalid operations at compile time:
struct Connection<State> { /* ... */ _state: PhantomData<State> }
struct Disconnected;
struct Connected;
impl Connection<Connected> {
fn send(&self, data: &[u8]) { /* only connected can send */ }
}
Documentation
// comments explain why (safety, workarounds, design rationale)
/// doc comments explain what and how for public APIs
- Every
TODO needs a linked issue: // TODO(#42): ...
- Enable
#![deny(missing_docs)] for libraries
1---2name: rust-best-practices3description: >4 Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. Use this skill when:5 (1) writing new Rust code or functions,6 (2) reviewing or refactoring existing Rust code,7 (3) deciding between borrowing vs cloning or ownership patterns,8 (4) implementing error handling with Result types,9 (5) optimizing Rust code for performance,10 (6) writing tests or documentation for Rust projects.11license: MIT12compatibility: Rust 1.70+, Cargo13metadata:14 source: https://skillmd.com/skills/comeonoliver/rust-best-practices15 author: apollographql16 version: "1.1.0"17allowed-tools: Bash(cargo:*) Bash(rustc:*) Bash(rustfmt:*) Bash(clippy:*) Read Write Edit Glob Grep18---1920# Rust Best Practices2122Apply these guidelines when writing or reviewing Rust code. Based on Apollo GraphQL's [Rust Best Practices Handbook](https://github.com/apollographql/rust-best-practices).2324## Best Practices Reference2526Before reviewing, familiarize yourself with Apollo's Rust best practices. Read ALL relevant chapters in the same turn in parallel. Reference these files when providing feedback:2728- [Chapter 1 - Coding Styles and Idioms](references/chapter_01.md): Borrowing vs cloning, Copy trait, Option/Result handling, iterators, comments29- [Chapter 2 - Clippy and Linting](references/chapter_02.md): Clippy configuration, important lints, workspace lint setup30- [Chapter 3 - Performance Mindset](references/chapter_03.md): Profiling, avoiding redundant clones, stack vs heap, zero-cost abstractions31- [Chapter 4 - Error Handling](references/chapter_04.md): Result vs panic, thiserror vs anyhow, error hierarchies32- [Chapter 5 - Automated Testing](references/chapter_05.md): Test naming, one assertion per test, snapshot testing33- [Chapter 6 - Generics and Dispatch](references/chapter_06.md): Static vs dynamic dispatch, trait objects34- [Chapter 7 - Type State Pattern](references/chapter_07.md): Compile-time state safety, when to use it35- [Chapter 8 - Comments vs Documentation](references/chapter_08.md): When to comment, doc comments, rustdoc36- [Chapter 9 - Understanding Pointers](references/chapter_09.md): Thread safety, Send/Sync, pointer types3738## Quick Reference3940### Borrowing & Ownership41- Prefer `&T` over `.clone()` unless ownership transfer is required42- Use `&str` over `String`, `&[T]` over `Vec<T>` in function parameters43- Small `Copy` types (≤24 bytes) can be passed by value44- Use `Cow<'_, T>` when ownership is ambiguous4546### Error Handling47- Return `Result<T, E>` for fallible operations; avoid `panic!` in production48- Never use `unwrap()`/`expect()` outside tests49- Use `thiserror` for library errors, `anyhow` for binaries only50- Prefer `?` operator over match chains for error propagation5152### Performance53- Always benchmark with `--release` flag54- Run `cargo clippy -- -D clippy::perf` for performance hints55- Avoid cloning in loops; use `.iter()` instead of `.into_iter()` for Copy types56- Prefer iterators over manual loops; avoid intermediate `.collect()` calls5758### Linting59Run regularly: `cargo clippy --all-targets --all-features --locked -- -D warnings`6061Key lints to watch:62- `redundant_clone` - unnecessary cloning63- `large_enum_variant` - oversized variants (consider boxing)64- `needless_collect` - premature collection6566Use `#[expect(clippy::lint)]` over `#[allow(...)]` with justification comment.6768### Testing69- Name tests descriptively: `process_should_return_error_when_input_empty()`70- One assertion per test when possible71- Use doc tests (`///`) for public API examples72- Consider `cargo insta` for snapshot testing generated output7374### Generics & Dispatch75- Prefer generics (static dispatch) for performance-critical code76- Use `dyn Trait` only when heterogeneous collections are needed77- Box at API boundaries, not internally7879### Type State Pattern80Encode valid states in the type system to catch invalid operations at compile time:81```rust82struct Connection<State> { /* ... */ _state: PhantomData<State> }83struct Disconnected;84struct Connected;8586impl Connection<Connected> {87 fn send(&self, data: &[u8]) { /* only connected can send */ }88}89```9091### Documentation92- `//` comments explain *why* (safety, workarounds, design rationale)93- `///` doc comments explain *what* and *how* for public APIs94- Every `TODO` needs a linked issue: `// TODO(#42): ...`95- Enable `#![deny(missing_docs)]` for libraries96