Rust Best Practices

When to Apply

• Writing new Rust code or designing APIs
• Reviewing or refactoring existing Rust code
• Implementing async systems with Tokio
• Designing error hierarchies with thiserror/anyhow
• Choosing between borrowing, cloning, or ownership transfer
• Setting up tests, benchmarks, or snapshot testing
• Configuring clippy lints and workspace settings
• Optimizing Rust code for performance

Reference Guide

references/coding-style.md

references/error-handling.md

references/ownership-and-pointers.md

references/traits-and-generics.md

references/async-and-concurrency.md

references/concurrency-sync.md

references/testing.md

references/performance.md

references/clippy-and-linting.md

references/documentation.md

Quick Reference: Coding Style

• Prefer

  &T

  over

  .clone()

  unless ownership transfer is required
• Use

  &str

  over

  String

  ,

  &[T]

  over

  Vec<T>

  in function parameters
• No

  get_

  prefix on getters:

  fn name()

  not

  fn get_name()

• Conversion naming:

  as_

  (cheap borrow),

  to_

  (expensive/cloning),

  into_

  (ownership transfer)
• Iterator methods:

  iter()

  /

  iter_mut()

  /

  into_iter()

• Import ordering:

  std

  -> external crates -> workspace crates ->

  super::

  ->

  crate::

• Comments explain why (safety, workarounds), not what
• Use

  format!

  over string concatenation with

  +

• Prefer

  s.bytes()

  over

  s.chars()

  for ASCII-only operations
• Avoid macros unless necessary; prefer functions or generics

Quick Reference: Error Handling

• Return

  Result<T, E>

  for fallible operations; reserve

  panic!

  for unrecoverable bugs
• No

  unwrap()

  in production. Use

  expect()

  with descriptive message only when the value is logically guaranteed. Prefer

  ?

  ,

  if let

  ,

  let...else

  for all other cases
• Use

  thiserror

  for library/crate errors,

  anyhow

  for binaries only
• Prefer

  ?

  operator over

  match

  chains for error propagation
• Use

  _else

  variants (

  ok_or_else

  ,

  unwrap_or_else

  ) to prevent eager allocation
• Use

  inspect_err

  and

  map_err

  for logging and transforming errors

• assert!

  at function entry for invariant checking (debug builds)

Quick Reference: Ownership & Pointers

• Small

  Copy

  types (<=24 bytes, all fields

  Copy

  , no heap) pass by value
• Use

  Cow<'_, T>

  when data may or may not need ownership
• Meaningful lifetime names:

  'src

  ,

  'ctx

  ,

  'conn

  — not just

  'a

• Use

  try_borrow()

  on

  RefCell

  to avoid panics; prefer over direct

  .borrow_mut()

• Shadowing for transformations:

  let x = x.parse()?

Box<T>

Rc<T>

Arc<T>

Cell<T>

RefCell<T>

Mutex<T>

RwLock<T>

Quick Reference: Traits & Generics

• Prefer generics (static dispatch) by default for zero-cost abstractions
• Use

  dyn Trait

  only when heterogeneous collections or plugin architectures are needed
• Box at API boundaries, not internally
• Object safety: no generic methods, no

  Self: Sized

  , methods use

  &self

  /

  &mut self

  /

  self

• Use sealed traits to prevent external implementors
• Type state pattern encodes valid states in the type system:

struct Connection<S> { _state: PhantomData<S> }
struct Disconnected;
struct Connected;
impl Connection<Connected> { fn send(&self, data: &[u8]) { /* ... */ } }

Quick Reference: Async & Concurrency

• Async for I/O-bound work, sync for CPU-bound work
• Never hold locks across

  .await

  points — use scoped guards
• Never use

  std::thread::sleep

  in async — use

  tokio::time::sleep

• Never spawn unboundedly — use semaphores for limits
• Ensure

  Send

  bounds on spawned futures
• Use

  JoinSet

  for managing multiple concurrent tasks
• Use

  CancellationToken

  (from

  tokio_util

  ) for graceful shutdown
• Instrument with

  tracing

  +

  #[instrument]

  for async debugging

mpsc

broadcast

oneshot

watch

• Sync channels:

  crossbeam::channel

  over

  std::sync::mpsc

• Async channels:

  tokio::sync::{mpsc, broadcast, oneshot, watch}

• Atomics (

  AtomicBool

  ,

  AtomicUsize

  ) over

  Mutex

  for primitive types
• Choose memory ordering carefully:

  Relaxed

  /

  Acquire

  /

  Release

  /

  SeqCst

Quick Reference: Testing

• Name tests descriptively:

  process_should_return_error_when_input_empty()

• One assertion per test when possible; include formatted failure messages
• Group tests in

  mod

  blocks by unit of work
• Use doc tests (

  ///

  ) for public API examples; run separately with

  cargo test --doc

• Snapshot testing:

  cargo insta test

  then

  cargo insta review

  ; redact unstable fields

• rstest

  for parameterized tests with

  #[case::name]

  labels

• proptest

  for property-based testing with custom strategies

• mockall

  with

  #[automock]

  for mocking traits

• criterion

  for benchmarks with

  iter_batched

  and

  BenchmarkId

• cargo-fuzz

  with

  libfuzzer_sys

  for fuzz testing

• cargo-tarpaulin

  or

  cargo-llvm-cov

  for code coverage

• sqlx::test

  for database integration tests with automatic pool injection
• Use

  #[should_panic]

  and

  #[ignore]

  attributes where appropriate

Quick Reference: Performance

• Golden rule: don't guess, measure. Always benchmark with

  --release

• Run

  cargo clippy -- -D clippy::perf

  for performance-related hints
• Use

  cargo flamegraph

  or

  samply

  (macOS) for profiling
• Avoid cloning in loops; clone at the last moment only
• Pre-allocate:

  Vec::with_capacity()

  ,

  String::with_capacity()

• Prefer iterators over manual

  for

  loops; avoid intermediate

  .collect()

• Stack for small types, heap for large/recursive; use

  smallvec

  for large const arrays
• Use

  Cow<'_, T>

  to avoid unnecessary allocation
• Prefer

  s.bytes()

  over

  s.chars()

  for ASCII-only string operations

Quick Reference: Clippy & Linting

cargo clippy --all-targets --all-features --locked -- -D warnings

redundant_clone

.clone()

needless_borrow

&

large_enum_variant

Box

needless_collect

.collect()

map_unwrap_or

.map().unwrap_or()

unnecessary_wraps

Ok

Some

clone_on_copy

.clone()

Copy

• Use

  #[expect(clippy::lint)]

  over

  #[allow(...)]

  —

  expect

  warns when lint no longer applies
• Add justification comment on every suppression
• Set

  #![warn(clippy::all)]

  as workspace minimum
• Configure workspace lints in

  Cargo.toml

  with priority levels

Quick Reference: Documentation

• //

  comments explain why: safety invariants, workarounds, design rationale

• ///

  doc comments explain what and how for all public items

• //!

  for module-level and crate-level documentation at top of

  lib.rs

  /

  mod.rs

• Every

  TODO

  needs a linked issue:

  // TODO(#42): description

• Enable

  #![deny(missing_docs)]

  for libraries
• Include

  # Examples

  ,

  # Errors

  ,

  # Panics

  ,

  # Safety

  sections in doc comments

missing_docs

broken_intra_doc_links

missing_panics_doc

missing_errors_doc

missing_safety_doc

Quick Reference: Data Types & Patterns

• Use newtypes for domain semantics:

  struct Email(String)

• Prefer slice patterns:

  if let [first, .., last] = slice

• Use arrays for fixed sizes; avoid

  Vec

  when length is known at compile time
• Shadowing for transformation:

  let x = x.parse()?

• Cow<str>

  when data might need modification of borrowed data

• contains()

  on strings is O(n*m) — avoid nested string iteration

Deprecated to Modern Migration

lazy_static!

std::sync::OnceLock

once_cell::Lazy

std::sync::LazyLock

std::sync::mpsc

crossbeam::channel

std::sync::Mutex

parking_lot::Mutex

failure

error-chain

thiserror

anyhow

try!()

?

async-trait

async fn

Cargo.toml Essentials

[dependencies]
thiserror = "2"
anyhow = "1"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
tracing = "0.1"
tracing-subscriber = "0.3"

[dev-dependencies]
rstest = "0.25"
proptest = "1"
mockall = "0.13"
criterion = { version = "0.5", features = ["html_reports"] }
insta = { version = "1", features = ["yaml"] }

Cargo.toml

[workspace.lints.clippy]
all = { level = "warn", priority = -1 }
pedantic = { level = "warn", priority = -1 }

rustfmt.toml

reorder_imports = true
imports_granularity = "Crate"
group_imports = "StdExternalCrate"

Constraints

MUST DO

1. Use ownership and borrowing for memory safety
2. Handle all errors explicitly via

   Result

   /

   Option

   — no silent failures
3. Use

   thiserror

   for library errors,

   anyhow

   for binaries
4. Minimize

   unsafe

   code; document all

   unsafe

   blocks with safety invariants
5. Use the type system for compile-time guarantees
6. Run

   cargo clippy

   and fix all warnings
7. Use

   cargo fmt

   for consistent formatting
8. Write tests including doc tests for public APIs
9. Add

   ///

   documentation with examples for all public items
10. Use

    tracing

    for observability in async code
11. When reviewing or writing code, suggest a testing approach using the recommended tools (

    rstest

    ,

    proptest

    ,

    insta

    ,

    mockall

    ,

    criterion

    ) — even if the user did not ask for tests

MUST NOT DO

1. Use

   unwrap()

   in production code
2. Create memory leaks or dangling pointers
3. Use

   unsafe

   without documented safety invariants
4. Ignore clippy warnings without

   #[expect(...)]

   and justification
5. Hold locks across

   .await

   points
6. Use

   std::thread::sleep

   in async context
7. Skip error handling or use

   panic!

   for recoverable errors
8. Use

   String

   where

   &str

   suffices; clone unnecessarily
9. Spawn tasks unboundedly without semaphore limits
10. Mix blocking and async code without

    spawn_blocking