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, when to extract a function (duplication vs. wrong abstraction)
- 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-practices
3description: >
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: MIT
12compatibility: Rust 1.70+, Cargo
13metadata:
14 source: https://skillmd.com/skills/apollographql/rust-best-practices
15 author: apollographql
16 version: "1.1.1"
17allowed-tools: Bash(cargo:*) Bash(rustc:*) Bash(rustfmt:*) Bash(clippy:*) Read Write Edit Glob Grep
18---
19
20# Rust Best Practices
21
22Apply these guidelines when writing or reviewing Rust code. Based on Apollo GraphQL's [Rust Best Practices Handbook](https://github.com/apollographql/rust-best-practices).
23
24## Best Practices Reference
25
26Before 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:
27
28- [Chapter 1 - Coding Styles and Idioms](references/chapter_01.md): Borrowing vs cloning, Copy trait, Option/Result handling, iterators, comments, when to extract a function (duplication vs. wrong abstraction)
29- [Chapter 2 - Clippy and Linting](references/chapter_02.md): Clippy configuration, important lints, workspace lint setup
30- [Chapter 3 - Performance Mindset](references/chapter_03.md): Profiling, avoiding redundant clones, stack vs heap, zero-cost abstractions
31- [Chapter 4 - Error Handling](references/chapter_04.md): Result vs panic, thiserror vs anyhow, error hierarchies
32- [Chapter 5 - Automated Testing](references/chapter_05.md): Test naming, one assertion per test, snapshot testing
33- [Chapter 6 - Generics and Dispatch](references/chapter_06.md): Static vs dynamic dispatch, trait objects
34- [Chapter 7 - Type State Pattern](references/chapter_07.md): Compile-time state safety, when to use it
35- [Chapter 8 - Comments vs Documentation](references/chapter_08.md): When to comment, doc comments, rustdoc
36- [Chapter 9 - Understanding Pointers](references/chapter_09.md): Thread safety, Send/Sync, pointer types
37
38## Quick Reference
39
40### Borrowing & Ownership
41- Prefer `&T` over `.clone()` unless ownership transfer is required
42- Use `&str` over `String`, `&[T]` over `Vec<T>` in function parameters
43- Small `Copy` types (≤24 bytes) can be passed by value
44- Use `Cow<'_, T>` when ownership is ambiguous
45
46### Error Handling
47- Return `Result<T, E>` for fallible operations; avoid `panic!` in production
48- Never use `unwrap()`/`expect()` outside tests
49- Use `thiserror` for library errors, `anyhow` for binaries only
50- Prefer `?` operator over match chains for error propagation
51
52### Performance
53- Always benchmark with `--release` flag
54- Run `cargo clippy -- -D clippy::perf` for performance hints
55- Avoid cloning in loops; use `.iter()` instead of `.into_iter()` for Copy types
56- Prefer iterators over manual loops; avoid intermediate `.collect()` calls
57
58### Linting
59Run regularly: `cargo clippy --all-targets --all-features --locked -- -D warnings`
60
61Key lints to watch:
62- `redundant_clone` - unnecessary cloning
63- `large_enum_variant` - oversized variants (consider boxing)
64- `needless_collect` - premature collection
65
66Use `#[expect(clippy::lint)]` over `#[allow(...)]` with justification comment.
67
68### Testing
69- Name tests descriptively: `process_should_return_error_when_input_empty()`
70- One assertion per test when possible
71- Use doc tests (`///`) for public API examples
72- Consider `cargo insta` for snapshot testing generated output
73
74### Generics & Dispatch
75- Prefer generics (static dispatch) for performance-critical code
76- Use `dyn Trait` only when heterogeneous collections are needed
77- Box at API boundaries, not internally
78
79### Type State Pattern
80Encode valid states in the type system to catch invalid operations at compile time:
81```rust
82struct Connection<State> { /* ... */ _state: PhantomData<State> }
83struct Disconnected;
84struct Connected;
85
86impl Connection<Connected> {
87 fn send(&self, data: &[u8]) { /* only connected can send */ }
88}
89```
90
91### Documentation
92- `//` comments explain *why* (safety, workarounds, design rationale)
93- `///` doc comments explain *what* and *how* for public APIs
94- Every `TODO` needs a linked issue: `// TODO(#42): ...`
95- Enable `#![deny(missing_docs)]` for libraries