Rust Best Practices

Comprehensive guide for writing high-quality, idiomatic, and highly optimized Rust code. Contains 179 rules across 14 categories, prioritized by impact to guide LLMs in code generation and refactoring.

When to Apply

Reference these guidelines when:

• Writing new Rust functions, structs, or modules
• Implementing error handling or async code
• Designing public APIs for libraries
• Reviewing code for ownership/borrowing issues
• Optimizing memory usage or reducing allocations
• Tuning performance for hot paths
• Refactoring existing Rust code

Rule Categories by Priority

Quick Reference

1. Ownership & Borrowing (CRITICAL)

• own-borrow-over-clone - Prefer &T borrowing over .clone()
• own-slice-over-vec - Accept &[T] not &Vec<T>, &str not &String
• own-cow-conditional - Use Cow<'a, T> for conditional ownership
• own-arc-shared - Use Arc<T> for thread-safe shared ownership
• own-rc-single-thread - Use Rc<T> for single-threaded sharing
• own-refcell-interior - Use RefCell<T> for interior mutability (single-thread)
• own-mutex-interior - Use Mutex<T> for interior mutability (multi-thread)
• own-rwlock-readers - Use RwLock<T> when reads dominate writes
• own-copy-small - Derive Copy for small, trivial types
• own-clone-explicit - Make Clone explicit, avoid implicit copies
• own-move-large - Move large data instead of cloning
• own-lifetime-elision - Rely on lifetime elision when possible

2. Error Handling (CRITICAL)

• err-thiserror-lib - Use thiserror for library error types
• err-anyhow-app - Use anyhow for application error handling
• err-result-over-panic - Return Result, don't panic on expected errors
• err-context-chain - Add context with .context() or .with_context()
• err-no-unwrap-prod - Never use .unwrap() in production code
• err-expect-bugs-only - Use .expect() only for programming errors
• err-question-mark - Use ? operator for clean propagation
• err-from-impl - Use #[from] for automatic error conversion
• err-source-chain - Use #[source] to chain underlying errors
• err-lowercase-msg - Error messages: lowercase, no trailing punctuation
• err-doc-errors - Document errors with # Errors section
• err-custom-type - Create custom error types, not Box<dyn Error>

3. Memory Optimization (CRITICAL)

• mem-with-capacity - Use with_capacity() when size is known
• mem-smallvec - Use SmallVec for usually-small collections
• mem-arrayvec - Use ArrayVec for bounded-size collections
• mem-box-large-variant - Box large enum variants to reduce type size
• mem-boxed-slice - Use Box<[T]> instead of Vec<T> when fixed
• mem-thinvec - Use ThinVec for often-empty vectors
• mem-clone-from - Use clone_from() to reuse allocations
• mem-reuse-collections - Reuse collections with clear() in loops
• mem-avoid-format - Avoid format!() when string literals work
• mem-write-over-format - Use write!() instead of format!()
• mem-arena-allocator - Use arena allocators for batch allocations
• mem-zero-copy - Use zero-copy patterns with slices and Bytes
• mem-compact-string - Use CompactString for small string optimization
• mem-smaller-integers - Use smallest integer type that fits
• mem-assert-type-size - Assert hot type sizes to prevent regressions

4. API Design (HIGH)

• api-builder-pattern - Use Builder pattern for complex construction
• api-builder-must-use - Add #[must_use] to builder types
• api-newtype-safety - Use newtypes for type-safe distinctions
• api-typestate - Use typestate for compile-time state machines
• api-sealed-trait - Seal traits to prevent external implementations
• api-extension-trait - Use extension traits to add methods to foreign types
• api-parse-dont-validate - Parse into validated types at boundaries
• api-impl-into - Accept impl Into<T> for flexible string inputs
• api-impl-asref - Accept impl AsRef<T> for borrowed inputs
• api-must-use - Add #[must_use] to Result returning functions
• api-non-exhaustive - Use #[non_exhaustive] for future-proof enums/structs
• api-from-not-into - Implement From, not Into (auto-derived)
• api-default-impl - Implement Default for sensible defaults
• api-common-traits - Implement Debug, Clone, PartialEq eagerly
• api-serde-optional - Gate Serialize/Deserialize behind feature flag

5. Async/Await (HIGH)

• async-tokio-runtime - Use Tokio for production async runtime
• async-no-lock-await - Never hold Mutex/RwLock across .await
• async-spawn-blocking - Use spawn_blocking for CPU-intensive work
• async-tokio-fs - Use tokio::fs not std::fs in async code
• async-cancellation-token - Use CancellationToken for graceful shutdown
• async-join-parallel - Use tokio::join! for parallel operations
• async-try-join - Use tokio::try_join! for fallible parallel ops
• async-select-racing - Use tokio::select! for racing/timeouts
• async-bounded-channel - Use bounded channels for backpressure
• async-mpsc-queue - Use mpsc for work queues
• async-broadcast-pubsub - Use broadcast for pub/sub patterns
• [async-watch-latest](rules