Rust Best Practices

Rust Best Practices

Apply these guidelines when writing or reviewing Rust code. Based on Apollo GraphQL's Rust Best Practices Handbook.

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

Detailed References

For in-depth guidance on specific topics:

• Coding style & idioms: See references/​style.md for borrowing patterns, Option/​Result handling, iterator usage, and import organization
• Error handling: See references/​errors.md for thiserror patterns, error hierarchies, and testing errors
• Performance: See references/​performance.md for profiling, memory layout, and iterator optimization
• Testing: See references/​testing.md for test organization, snapshot testing, and assertion strategies
• Advanced patterns: See references/​advanced.md for generics, dispatch, type state, and pointer types