Rust Best Practices

Comprehensive guide for writing high-quality, idiomatic, and highly optimized Rust code. Contains 265 rules across 26 categories, prioritized by impact to guide LLMs in code generation and refactoring. Current for Rust 1.96 (2024 edition).

When to Apply

Reference these guidelines when:

• Writing new Rust functions, structs, or modules
• Implementing error handling or async code
• Writing concurrent, parallel, or unsafe 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

Priority	Category	Impact	Prefix	Rules
1	Ownership & Borrowing	CRITICAL	own-	12
2	Error Handling	CRITICAL	err-	12
3	Memory Optimization	CRITICAL	mem-	17
4	Unsafe Code	CRITICAL	unsafe-	7
5	API Design	HIGH	api-	17
6	Async/Await	HIGH	async-	18
7	Concurrency	HIGH	conc-	4
8	Compiler Optimization	HIGH	opt-	12
9	Numeric & Arithmetic Safety	HIGH	num-	5
10	Type Safety	MEDIUM	type-	13
11	Trait & Generics Design	MEDIUM	trait-	6
12	Conversions	MEDIUM	conv-	3
13	Const & Compile-Time	MEDIUM	const-	4
14	Serde	MEDIUM	serde-	8
15	Pattern Matching	MEDIUM	pat-	5
16	Macros	MEDIUM	macro-	8
17	Closures	MEDIUM	closure-	5
18	Collections	MEDIUM	coll-	4
19	Naming Conventions	MEDIUM	name-	16
20	Testing	MEDIUM	test-	15
21	Documentation	MEDIUM	doc-	12
22	Observability	MEDIUM	obs-	7
23	Performance Patterns	MEDIUM	perf-	13
24	Project Structure	LOW	proj-	14
25	Clippy & Linting	LOW	lint-	13
26	Anti-patterns	REFERENCE	anti-	15

---

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 shared ownership in single-threaded contexts
• own-refcell-interior - Use RefCell<T> for interior mutability in single-threaded code
• own-mutex-interior - Use Mutex<T> for interior mutability across threads
• own-rwlock-readers - Use RwLock<T> when reads significantly outnumber writes
• own-copy-small - Implement Copy for small, simple types
• own-clone-explicit - Use explicit Clone for types where copying has meaningful cost
• own-move-large - Move large types instead of copying; use Box if moves are expensive
• own-lifetime-elision - Rely on lifetime elision rules; add explicit lifetimes only when required

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<T, E> instead of panicking for recoverable errors
• err-context-chain - Add context with .context() or .with_context()
• err-no-unwrap-prod - Avoid unwrap() in production code; use ?, expect(), or handle errors
• err-expect-bugs-only - Use expect() only for invariants that indicate bugs, not user errors
• err-question-mark - Use ? operator for clean propagation
• err-from-impl - Implement From<E> for error conversions to enable ? operator
• err-source-chain - Preserve error chains with #[source] or source() method
• err-lowercase-msg - Start error messages lowercase, no trailing punctuation
• err-doc-errors - Document error conditions with # Errors section in doc comments
• err-custom-type - Define custom error types for domain-specific failures

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<T, N> for fixed-capacity collections that never heap-allocate
• mem-box-large-variant - Box large enum variants to reduce overall enum size
• mem-boxed-slice - Use Box<[T]> instead of Vec<T> for fixed-size heap data
• mem-thinvec - Use ThinVec<T> for nullable collections with minimal overhead
• mem-clone-from - Use clone_from() to reuse allocations when repeatedly cloning
• mem-reuse-collections - Clear and reuse collections instead of creating new ones in loops
• mem-avoid-format - Avoid format!() when string literals work
• mem-write-over-format - Use write!() into existing buffers instead of format!() allocations
• mem-arena-allocator - Use arena allocators for batch allocations
• mem-zero-copy - Use zero-copy patterns with slices and Bytes
• mem-compact-string - Use compact string types for memory-constrained string storage
• mem-smaller-integers - Use appropriately-sized integers to reduce memory footprint
• mem-assert-type-size - Use static assertions to guard against accidental type size growth
• mem-take-replace - Use mem::take / mem::replace to move a value out of a &mut without cloning
• mem-drop-order - Know and control drop order: struct fields drop top-to-bottom, locals in reverse

4. Unsafe Code (CRITICAL)

• unsafe-safety-comment - Write a // SAFETY: comment above every unsafe block and a # Safety section in every unsafe fn.
• unsafe-minimize-scope - Keep unsafe blocks as small as possible — mark only the operation that requires unsafety, not the surrounding safe code.
• unsafe-miri-ci - Run cargo miri test in CI for every crate that contains unsafe code.
• unsafe-maybeuninit - Use MaybeUninit<T> for uninitialized memory; never use mem::uninitialized() or mem::zeroed() for types with validity invariants.
• unsafe-extern-block - In Rust 2024, wrap extern blocks in unsafe extern { } and annotate each item as safe or unsafe.
• unsafe-send-sync-manual - Document the invariants when manually implementing Send or Sync; prefer letting the compiler derive them automatically.
• unsafe-no-mangle-unsafe - In Rust 2024, write #[unsafe(no_mangle)], #[unsafe(export_name = "...")], and #[unsafe(link_section = "...")] — not the bare attribute forms.

5. API Design (HIGH)

• api-builder-pattern - Use Builder pattern for complex construction
• api-builder-must-use - Mark builder methods with #[must_use] to prevent silent drops
• api-newtype-safety - Use newtypes to prevent mixing semantically different values
• api-typestate - Use typestate pattern to encode state machine invariants in the type system
• api-sealed-trait - Use sealed traits to prevent external implementations while allowing use
• api-extension-trait - Use extension traits to add methods to external types
• api-parse-dont-validate - Parse into validated types at boundaries
• api-impl-into - Accept impl Into<T> for flexible APIs, implement From<T> for conversions
• api-impl-asref - Use AsRef<T> when you only need to borrow the inner data
• api-must-use - Mark types and functions with #[must_use] when ignoring results is likely a bug
• api-non-exhaustive - Use #[non_exhaustive] on public enums and structs for forward compatibility
• api-from-not-into - Implement From<T>, not Into<U> - From gives you Into for free
• api-default-impl - Implement Default for types with sensible default values
• api-common-traits - Implement standard traits (Debug, Clone, PartialEq, etc.) for public types
• api-serde-optional - Make serde a feature flag, not a hard dependency for library crates
• api-impl-fromiterator - Implement FromIterator and Extend for collection types, and IntoIterator for all three reference forms
• api-operator-overload - Overload operators only when the semantics are natural and unsurprising

6. Async/Await (HIGH)

• async-tokio-runtime - Configure Tokio runtime appropriately for your workload
• 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 instead of std::fs in async code
• async-cancellation-token - Use CancellationToken for graceful shutdown and task cancellation
• async-join-parallel - Use join! or try_join! for concurrent independent futures
• async-try-join - Use try_join! for concurrent fallible operations with early return on error
• async-select-racing - Use select! to race futures and handle the first to complete
• async-bounded-channel - Use bounded channels to apply backpressure and prevent unbounded memory growth
• async-mpsc-queue - Use mpsc channels for async message queues between tasks
• async-broadcast-pubsub - Use broadcast channel for pub/sub where all subscribers receive all messages
• async-watch-latest - Use watch channel for sharing the latest value with multiple observers
• async-oneshot-response - Use oneshot channel for request-response patterns
• async-joinset-structured - Use JoinSet for managing dynamic collections of spawned tasks
• async-clone-before-await - Clone Arc/Rc data before await points to avoid holding references across suspension
• async-fn-in-trait - Use native async fn in traits (stable 1.75) instead of the async_trait macro
• async-async-fn-bounds - Use AsyncFn/AsyncFnMut/AsyncFnOnce bounds instead of F: Fn() -> Fut, Fut: Future
• async-cancel-safety - Ensure futures used in tokio::select! branches are cancellation-safe

7. Concurrency (HIGH)

• conc-rayon-par-iter - Use rayon's par_iter() for CPU-bound data parallelism
• conc-scoped-threads - Use std::thread::scope to borrow stack data across threads
• conc-atomic-ordering - Use the weakest correct memory Ordering for every atomic operation
• conc-thread-local - Prefer thread_local! with Cell/RefCell over static mut

8. Compiler Optimization (HIGH)

• opt-inline-small - Use #[inline] for small hot functions
• opt-inline-always-rare - Use #[inline(always)] sparingly—only for critical hot paths proven by profiling
• opt-inline-never-cold - Use #[inline(never)] and #[cold] for error paths and rarely-executed code
• opt-cold-unlikely - Mark unlikely code paths with #[cold] to help compiler optimization
• opt-likely-hint - Use code structure to hint at likely branches; use intrinsics on nightly
• opt-lto-release - Enable LTO in release builds
• opt-codegen-units - Set codegen-units = 1 for maximum optimization in release builds
• opt-pgo-profile - Use Profile-Guided Optimization (PGO) for maximum performance
• opt-target-cpu - Use target-cpu=native for maximum performance on known deployment targets
• opt-bounds-check - Use iterators and patterns that eliminate bounds checks in hot paths
• opt-simd-portable - Use portable SIMD for vectorized operations across architectures
• opt-cache-friendly - Organize data for cache-efficient access patterns

9. Numeric & Arithmetic Safety (HIGH)

• num-overflow-explicit - Handle integer overflow explicitly: checked_/saturating_/wrapping_/overflowing_
• num-cast-try-from - Avoid as for narrowing casts; use From for widening and TryFrom for narrowing
• num-float-compare - Don't compare floats with ==; use a tolerance, and total_cmp for ordering
• num-saturating-clamp - Bound values with clamp and saturating arithmetic
• num-nonzero - Use NonZero* types to forbid zero and unlock the niche optimization

10. Type Safety (MEDIUM)

• type-newtype-ids - Wrap IDs in newtypes: UserId(u64)
• type-newtype-validated - Use newtypes to enforce validation at construction time
• type-enum-states - Use enums for mutually exclusive states
• type-option-nullable - Use Option<T> for values that might not exist
• type-result-fallible - Use Result<T, E> for operations that can fail
• type-phantom-marker - Use PhantomData to express type relationships without runtime cost
• type-never-diverge - Use ! (never type) for functions that never return
• type-generic-bounds - Add trait bounds only where needed, prefer where clauses for readability
• type-no-stringly - Avoid stringly-typed APIs; use enums, newtypes, or validated types
• type-repr-transparent - Use #[repr(transparent)] for newtypes in FFI contexts
• type-deref-coercion - Implement Deref/DerefMut only for smart-pointer and transparent wrapper types
• type-display-vs-debug - Use Display for user-facing output and Debug for diagnostics; never swap them
• type-numeric-fmt - Implement LowerHex, UpperHex, Octal, and Binary for numeric newtypes

11. Trait & Generics Design (MEDIUM)

• trait-associated-type-vs-generic - Use an associated type when each impl has exactly one output type; use a generic parameter when a type can implement the trait for many input types
• trait-blanket-impl - Use a blanket impl impl<T: Bound> Trait for T to give behaviour to every type that satisfies a bound
• trait-coherence-newtype - Respect the orphan rule; wrap a foreign type in a newtype to implement a foreign trait on it
• trait-default-methods - Define a trait in terms of a few required methods plus defaulted ones built on top of them
• trait-dyn-vs-generic - Choose static dispatch (generics / impl Trait) vs dynamic dispatch (dyn Trait) deliberately
• trait-object-safety - Keep a trait dyn-compatible (object-safe) when you need dyn Trait

12. Conversions (MEDIUM)

• conv-tryfrom-fallible - Implement TryFrom for fallible conversions instead of ad-hoc conversion functions
• conv-fromstr-parsing - Implement FromStr to enable str::parse for string-to-type conversions
• conv-asmut-mutable - Accept impl AsMut<T> for flexible mutable borrowed inputs instead of concrete mutable references

13. Const & Compile-Time (MEDIUM)

• const-block - Use inline const { } blocks for compile-time evaluation and assertions
• const-fn - Make functions const fn when they can run at compile time
• const-generics - Parameterize over values with const generics <const N: usize>
• const-vs-static - Use const for an inlined value and static for a single addressed instance

14. Serde (MEDIUM)

• serde-rename-all - Match the external naming convention with #[serde(rename_all = ...)]
• serde-default-compat - Use #[serde(default)] for optional and backward-compatible fields
• serde-skip-empty - Omit empty fields with skip_serializing_if
• serde-flatten - Inline nested structs or capture extra keys with #[serde(flatten)]
• serde-enum-representation - Choose enum tagging deliberately: externally, internally, adjacently tagged, or untagged
• serde-deny-unknown-fields - Reject unexpected keys with #[serde(deny_unknown_fields)]
• serde-custom-with - Customize a field's (de)serialization with with / serialize_with / deserialize_with
• serde-try-from-validate - Validate while deserializing with #[serde(try_from = "Raw")]

15. Pattern Matching (MEDIUM)

• pat-let-else - Use let ... else for early-return pattern extraction
• pat-matches-macro - Use matches!() for boolean pattern tests
• pat-if-let-chains - Use if let chains to combine pattern bindings and conditions
• pat-exhaustive-enum - Match owned enums exhaustively; avoid catch-all _ that hides new variants
• pat-at-bindings - Use @ bindings to capture a value while matching it against a pattern

16. Macros (MEDIUM)

• macro-prefer-functions - Reach for a macro only when a function or generic cannot express it
• macro-rules-hygiene - Rely on macro_rules! hygiene and use $crate for paths to your crate's items
• macro-fragment-specifiers - Capture with precise fragment specifiers, not raw :tt, where you can
• macro-export-crate-path - Export declarative macros with #[macro_export] and a clean import path
• macro-private-helpers - Hide macro-generated helper items behind a #[doc(hidden)] pub mod __private
• macro-proc-two-crate - Put procedural macros in a dedicated proc-macro = true crate and re-export from the facade
• macro-proc-syn-quote - Build procedural macros with syn, quote, and proc-macro2
• macro-proc-error-spans - Report proc-macro errors as spanned compile errors, never by panicking

17. Closures (MEDIUM)

• closure-fn-trait-bounds - Require the least restrictive Fn trait a callback needs (FnOnce ⊇ FnMut ⊇ Fn)
• closure-impl-fn-return - Return closures as impl Fn/FnMut/FnOnce, not Box<dyn Fn>
• closure-move-capture - Use move for closures that outlive the current scope; clone before move to keep the original
• closure-static-vs-dyn - Accept impl Fn (generic) for hot callbacks; use &dyn Fn/Box<dyn Fn> to cut code size or to store them
• closure-disjoint-capture - Capture only what you use; lean on edition-2021 disjoint closure captures

18. Collections (MEDIUM)

• coll-binaryheap - Use BinaryHeap for a priority queue or repeated max-extraction
• coll-map-choice - Pick the map by access pattern: HashMap (fast, unordered), BTreeMap (sorted / range queries), IndexMap (insertion order)
• coll-seq-choice - Default to Vec; use VecDeque for queue/deque behaviour; avoid LinkedList
• coll-set-membership - Use HashSet/BTreeSet for membership tests and dedup, not linear Vec::contains

19. Naming Conventions (MEDIUM)