rust-best-practices

Rust best practices

Produce idiomatic Rust that satisfies the requested behaviour and the project's contracts. Follow repository instructions, established conventions, and supported toolchains. Keep changes scoped; do not replace working architecture or introduce dependencies solely to satisfy a preference here.

Establish the contract

Read the affected code, tests, Cargo manifests, toolchain configuration, and relevant CI commands. Identify the edition, minimum supported Rust version (MSRV), deployment targets, feature combinations, and whether the changed interface has downstream consumers. A lib.rs alone does not imply a published compatibility promise.

Before refactoring, establish observable behaviour and relevant failure semantics. Preserve public signatures, errors, output, and feature behaviour unless the request authorises changes. A panic-to-error conversion can change a public signature; explain the migration rather than assuming it is compatible. Add focused regression coverage for demonstrated bugs or fragile behaviour.

Implement with explicit contracts

• Prefer clear concrete types and direct code. Use enums or newtypes when they prevent meaningful invalid states or unit confusion; introduce traits and builders for actual variation or construction needs.
• Borrow when reading, use mutable borrows for in-place updates, and consume by value when storing or transferring ownership. Prefer &str and slices when callers need no container-specific operations. Choose generic conversion/iterator parameters only when their flexibility earns the complexity.
• Start with unique ownership. Use Arc, Rc, locks, and interior mutability when sharing or mutation is intentional. Their presence in an API is a design question, not automatically a defect. Before cloning to resolve a borrow conflict, consider shortening the borrow, separating disjoint state, or moving with take/replace; deliberate cheap copies are valid.
• Use Option for normal absence, Result for expected failures, and panics for violated internal invariants. Check whether external input can violate a claimed invariant. A justified expect should explain the invariant; do not mechanically replace every unwrap or promise panic-free behaviour without evidence.
• Preserve actionable error context and causal chains. Public error types should support the contracts callers need, normally Display and Error; require Send, Sync, or 'static when the execution/API model needs them. Prefer typed errors when callers inspect failures; error erasure can be intentional. Do not add an error framework by default.
• Keep visibility narrow and public APIs intentional. Implement applicable standard traits and conversion conventions; use fallible conversions when validation can fail. Keep Eq, Ord, PartialOrd, and Hash consistent over the same semantic value. Derived implementations are fine when consistent with custom ones.
• Treat public fields, trait bounds, enum variants, feature behaviour, and exposed dependency types as compatibility decisions. Follow existing API conventions; do not add sealing, non_exhaustive, or new wrappers without considering their costs.
• Bound work and resource consumption for untrusted input. Check parser sizes, allocation growth, retries, and partial-failure cleanup where relevant; safe Rust does not prevent resource exhaustion.
• Handle integer range and conversion semantics explicitly at trust boundaries. Choose checked, saturating, wrapping, or fallible operations according to the contract. A numeric as cast can truncate; do not confuse truncation with a panic.
• Prefer readable iteration and pattern matching over mechanical rewrites between loops, combinators, and match. Avoid speculative abstraction and unmeasured optimisation. Keep externally visible ordering deterministic when the contract requires it.
• Document public contracts that types cannot express: failure modes, panics, safety obligations, side effects, and meaningful ownership or complexity constraints. Examples should demonstrate realistic error handling. Follow existing documentation conventions instead of imposing a template on every private helper.