Rust Community Idiomatic Rust Best Practices
A structured guide to writing idiomatic Rust code based on patterns established by top contributors. Each rule includes incorrect/correct examples with realistic domain names and quantified impact metrics.
When to Apply
- Writing new Rust code in any project or crate
- Reviewing pull requests for idiomatic patterns
- Refactoring code that uses excessive cloning, manual loops, or opaque error handling
- Designing public APIs for libraries or shared modules
- Optimizing async code for correctness and cancellation safety
Rule Categories by Priority
| # |
Category |
Prefix |
Impact |
Rules |
| 1 |
Ownership and Borrowing |
own- |
CRITICAL |
6 |
| 2 |
Error Propagation |
errprop- |
CRITICAL |
6 |
| 3 |
Type Safety |
safe- |
HIGH |
6 |
| 4 |
Collections and Iterators |
iter- |
HIGH |
5 |
| 5 |
Async Patterns |
asyncp- |
MEDIUM-HIGH |
5 |
| 6 |
API Design |
api- |
MEDIUM |
5 |
| 7 |
Serialization |
serial- |
MEDIUM |
4 |
| 8 |
Performance |
perf- |
LOW-MEDIUM |
4 |
|
Total |
|
|
41 |
Quick Reference
Ownership and Borrowing (CRITICAL)
own-borrow-over-clone - Borrow references instead of cloning
own-cow-conditional - Use Cow for conditional ownership
own-arc-shared-state - Use Arc for shared async state
own-avoid-unnecessary-clone - Avoid unnecessary clone in closures
own-move-closures-spawn - Use move closures for tokio spawn
own-into-conversions - Use Into conversions for ergonomic APIs
Error Propagation (CRITICAL)
errprop-question-mark - Use the question mark operator for error propagation
errprop-context-annotations - Add context to every fallible operation
errprop-custom-error-types - Define custom error types for domain boundaries
errprop-anyhow-applications - Use anyhow for application-level error handling
errprop-thiserror-libraries - Use thiserror for library error definitions
errprop-boundary-conversion - Convert errors at module boundaries
Type Safety (HIGH)
safe-newtype-identifiers - Use newtype pattern for type-safe identifiers
safe-enum-state-machines - Use enums to represent state machines
safe-builder-construction - Use builder pattern for complex object construction
safe-from-into-traits - Implement From and Into for type conversions
safe-non-exhaustive - Use non_exhaustive on public enums
safe-phantom-data - Use PhantomData for type-level constraints
Collections and Iterators (HIGH)
iter-btreemap-determinism - Use BTreeMap for deterministic iteration
iter-method-references - Use method references over closures
iter-collect-turbofish - Use turbofish on collect for clarity
iter-chain-over-loops - Prefer iterator chaining over manual loops
iter-filter-map - Use filter_map instead of filter then map
Async Patterns (MEDIUM-HIGH)
asyncp-tokio-select - Use tokio select for concurrent branch waiting
asyncp-pin-box-futures - Pin boxed futures to reduce async stack size
asyncp-cancellation-safety - Design for cancellation safety in async code
asyncp-send-bounds - Ensure futures are Send for multi-threaded runtimes
asyncp-structured-concurrency - Use JoinSet for structured concurrency
API Design (MEDIUM)
api-accept-asref - Accept impl AsRef for flexible string parameters
api-return-impl-iterator - Return impl Iterator over collected Vec
api-derive-default - Derive Default for configuration structs
api-display-user-facing - Implement Display for user-facing types
api-sealed-traits - Use sealed traits for extension prevention
Serialization (MEDIUM)
serial-rename-all - Use rename_all for consistent wire format
serial-deny-unknown - Use deny_unknown_fields for strict deserialization
serial-default-values - Use serde default for backward compatibility
serial-flatten-composition - Use serde flatten for struct composition
Performance (LOW-MEDIUM)
perf-preallocate-capacity - Pre-allocate Vec and String capacity
perf-cow-avoid-alloc - Use Cow to avoid unnecessary allocations
perf-arc-str - Use Arc str over Arc String for shared strings
perf-lazy-lock - Use LazyLock for thread-safe lazy initialization
How to Use
- Before writing code: Review the CRITICAL rules (Ownership, Error Propagation) as they prevent the most impactful bugs and performance issues.
- During implementation: Follow Type Safety and Collections rules to leverage the compiler as a correctness tool.
- When designing APIs: Apply API Design and Serialization rules to create ergonomic, evolution-safe interfaces.
- When optimizing: Use Performance rules for targeted improvements in measured hot paths.
Reference Files
| File |
Description |
references/_sections.md |
Section definitions and ordering |
references/own-*.md |
Ownership and borrowing rules (6 files) |
references/errprop-*.md |
Error propagation rules (6 files) |
references/safe-*.md |
Type safety rules (6 files) |
references/iter-*.md |
Collections and iterators rules (5 files) |
references/asyncp-*.md |
Async patterns rules (5 files) |
references/api-*.md |
API design rules (5 files) |
references/serial-*.md |
Serialization rules (4 files) |
references/perf-*.md |
Performance rules (4 files) |