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 – Use watch for latest-value sharing
• async-oneshot-response – Use oneshot for request/response
• async-joinset-structured – Use JoinSet for dynamic task groups
• async-clone-before-await – Clone data before await, release locks

6. Compiler Optimization (HIGH)

• opt-inline-small – Use #[inline] for small hot functions
• opt-inline-always-rare – Use #[inline(always)] sparingly
• opt-inline-never-cold – Use #[inline(never)] for cold paths
• opt-cold-unlikely – Use #[cold] for error/unlikely paths
• opt-likely-hint – Use likely()/unlikely() for branch hints
• opt-lto-release – Enable LTO in release builds
• opt-codegen-units – Use codegen-units = 1 for max optimization
• opt-pgo-profile – Use PGO for production builds
• opt-target-cpu – Set target-cpu=native for local builds
• opt-bounds-check – Use iterators to avoid bounds checks
• opt-simd-portable – Use portable SIMD for data-parallel ops
• opt-cache-friendly – Design cache-friendly data layouts (SoA)

7. Naming Conventions (MEDIUM)

• name-types-camel – Use UpperCamelCase for types, traits, enums
• name-variants-camel – Use UpperCamelCase for enum variants
• name-funcs-snake – Use snake_case for functions, methods, modules
• name-consts-screaming – Use SCREAMING_SNAKE_CASE for constants/statics
• name-lifetime-short – Use short lowercase lifetimes: 'a, 'de, 'src
• name-type-param-single – Use single uppercase for type params: T, E, K, V
• name-as-free – as_ prefix: free reference conversion
• name-to-expensive – to_ prefix: expensive conversion
• name-into-ownership – into_ prefix: ownership transfer
• name-no-get-prefix – No get_ prefix for simple getters
• name-is-has-bool – Use is_, has_, can_ for boolean methods
• name-iter-convention – Use iter/iter_mut/into_iter for iterators
• name-iter-method – Name iterator methods consistently
• name-iter-type-match – Iterator type names match method
• name-acronym-word – Treat acronyms as words: Uuid not UUID
• name-crate-no-rs – Crate names: no -rs suffix

8. Type Safety (MEDIUM)

• type-newtype-ids – Wrap IDs in newtypes: UserId(u64)
• type-newtype-validated – Newtypes for validated data: Email, Url
• type-enum-states – Use enums for mutually exclusive states
• type-option-nullable – Use Option<T> for nullable values
• type-result-fallible – Use Result<T, E> for fallible operations
• type-phantom-marker – Use PhantomData<T> for type-level markers
• type-never-diverge – Use ! type for functions that never return
• type-generic-bounds – Add trait bounds only where needed
• type-no-stringly – Avoid stringly-typed APIs, use enums/newtypes
• type-repr-transparent – Use #[repr(transparent)] for FFI newtypes

9. Testing (MEDIUM)

• test-cfg-test-module – Use #[cfg(test)] mod tests { }
• test-use-super – Use use super::*; in test modules
• test-integration-dir – Put integration tests in tests/ directory
• test-descriptive-names – Use descriptive test names
• test-arrange-act-assert – Structure tests as arrange/act/assert
• test-proptest-properties – Use proptest for property-based testing
• test-mockall-mocking – Use mockall for trait mocking
• test-mock-traits – Use traits for dependencies to enable mocking
• test-fixture-raii – Use RAII pattern (Drop) for test cleanup
• test-tokio-async – Use #[tokio::test] for async tests
• test-should-panic – Use #[should_panic] for panic tests
• test-criterion-bench – Use criterion for benchmarking
• test-doctest-examples – Keep doc examples as executable tests

10. Documentation (MEDIUM)

• doc-all-public – Document all public items with ///
• doc-module-inner – Use //! for module-level documentation
• doc-examples-section – Include # Examples with runnable code
• doc-errors-section – Include # Errors for fallible functions
• doc-panics-section – Include # Panics for panicking functions
• doc-safety-section – Include # Safety for unsafe functions
• doc-question-mark – Use ? in examples, not .unwrap()
• doc-hidden-setup – Use # prefix to hide example setup code
• doc-intra-links – Use intra-doc links: [Vec]
• doc-link-types – Link related types and functions in docs
• doc-cargo-metadata – Fill Cargo.toml metadata

11. Performance Patterns (MEDIUM)

• perf-iter-over-index – Prefer iterators over manual indexing
• perf-iter-lazy – Keep iterators lazy, collect() only when needed
• perf-collect-once – Don’t collect() intermediate iterators
• perf-entry-api – Use entry() API for map insert-or-update
• perf-drain-reuse – Use drain() to reuse allocations
• perf-extend-batch – Use extend() for batch insertions
• perf-chain-avoid – Avoid chain() in hot loops
• perf-collect-into – Use collect_into() for reusing containers
• perf-black-box-bench – Use black_box() in benchmarks
• perf-release-profile – Optimize release profile settings
• perf-profile-first – Profile before optimizing

12. Project Structure (LOW)

• proj-lib-main-split – Keep main.rs minimal, logic in lib.rs
• proj-mod-by-feature – Organize modules by feature, not type
• proj-flat-small – Keep small projects flat
• proj-mod-rs-dir – Use mod.rs for multi-file modules
• proj-pub-crate-internal – Use pub(crate) for internal APIs
• proj-pub-super-parent – Use pub(super) for parent-only visibility
• proj-pub-use-reexport – Use pub use for clean public API
• proj-prelude-module – Create prelude module for common imports
• proj-bin-dir – Put multiple binaries in src/bin/
• proj-workspace-large – Use workspaces for large projects
• proj-workspace-deps – Use workspace dependency inheritance

13. Clippy & Linting (LOW)

• lint-deny-correctness – #![deny(clippy::correctness)]
• lint-warn-suspicious – #![warn(clippy::suspicious)]
• lint-warn-style – #![warn(clippy::style)]
• lint-warn-complexity – #![warn(clippy::complexity)]
• lint-warn-perf – #![warn(clippy::perf)]
• lint-pedantic-selective – Enable clippy::pedantic selectively
• lint-missing-docs – #![warn(missing_docs)]
• lint-unsafe-doc – #![warn(clippy::undocumented_unsafe_blocks)]
• lint-cargo-metadata – #![warn(clippy::cargo)] for published crates
• lint-rustfmt-check – Run cargo fmt --check in CI
• lint-workspace-lints – Configure lints at workspace level

14. Anti-patterns (REFERENCE)

• anti-unwrap-abuse – Don’t use .unwrap() in production code
• anti-expect-lazy – Don’t use .expect() for recoverable errors
• anti-clone-excessive – Don’t clone when borrowing works
• anti-lock-across-await – Don’t hold locks across .await
• anti-string-for-str – Don’t accept &String when &str works
• anti-vec-for-slice – Don’t accept &Vec<T> when &[T] works
• anti-index-over-iter – Don’t use indexing when iterators work
• anti-panic-expected – Don’t panic on expected/recoverable errors
• anti-empty-catch – Don’t use empty if let Err(_) = ... blocks
• anti-over-abstraction – Don’t over-abstract with excessive generics
• anti-premature-optimize – Don’t optimize before profiling
• anti-type-erasure – Don’t use Box<dyn Trait> when impl Trait works
• anti-format-hot-path – Don’t use format!() in hot paths
• anti-collect-intermediate – Don’t collect() intermediate iterators
• anti-stringly-typed – Don’t use strings for structured data

Recommended Cargo.toml Settings

[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
panic = "abort"
strip = true

[profile.bench]
inherits = "release"
debug = true
strip = false

[profile.dev]
opt-level = 0
debug = true

[profile.dev.package."*"]
opt-level = 3  # Optimize dependencies in dev

How to Use

This skill provides rule identifiers for quick reference. When generating or reviewing Rust code:

1. Check relevant category based on task type
2. Apply rules with matching prefix
3. Prioritize CRITICAL > HIGH > MEDIUM > LOW
4. Read rule files in rules/ for detailed examples

Rule Application by Task

Sources

This skill synthesizes best practices from:

• Rust API Guidelines
• Rust Performance Book
• Rust Design Patterns
• Production codebases: ripgrep, tokio, serde, polars, axum, deno
• Clippy lint documentation
• Community conventions (2024-2025)