rust-idioms

Rust Community Rust Refactoring Best Practices

Comprehensive refactoring and idiomatic patterns guide for Rust applications, maintained by the Rust Community. Contains 44 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Rust code with strong type guarantees
• Refactoring ownership and borrowing patterns
• Designing error handling strategies
• Creating public APIs with traits and generics
• Organizing modules and controlling visibility

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Type Safety & Newtype Patterns	CRITICAL	type-
2	Ownership & Borrowing	CRITICAL	own-
3	Error Handling Patterns	HIGH	err-
4	API Design & Traits	HIGH	api-
5	Module & Visibility	MEDIUM-HIGH	mod-
6	Conversion Traits	MEDIUM	conv-
7	Idiomatic Patterns	MEDIUM	idiom-
8	Iterator & Collections	LOW-MEDIUM	iter-

Quick Reference

1. Type Safety & Newtype Patterns (CRITICAL)

• type-newtype-units - Use newtype pattern for unit safety
• type-newtype-invariants - Encode invariants in newtype constructors
• type-non-exhaustive-enums - Use non-exhaustive for extensible enums
• type-phantom-data - Use PhantomData for type-level state
• type-strong-typing-strings - Replace stringly-typed APIs with strong types
• type-builder-required-fields - Use typestate builders for required fields

2. Ownership & Borrowing (CRITICAL)

• own-prefer-borrowing - Prefer borrowing over ownership in parameters
• own-cow-conditional-clone - Use Cow for conditional ownership
• own-accept-borrowed-types - Accept borrowed types over owned references
• own-return-owned-for-flexibility - Return owned types for caller flexibility
• own-avoid-unnecessary-clone - Avoid unnecessary clone calls
• own-lifetime-elision - Leverage lifetime elision rules

3. Error Handling Patterns (HIGH)

• err-use-result-not-panic - Use Result instead of panic! for recoverable errors
• err-thiserror-for-libraries - Use thiserror for library error types
• err-anyhow-for-applications - Use anyhow for application error handling
• err-question-mark-propagation - Use the question mark operator for error propagation
• err-option-for-absence - Use Option for absence, not sentinel values

4. API Design & Traits (HIGH)

• api-derive-common-traits - Derive common traits for public types
• api-impl-standard-traits - Implement standard traits for ergonomic APIs
• api-generic-bounds - Use trait bounds for generic flexibility
• api-sealed-traits - Use sealed traits to prevent external implementation
• api-builder-pattern - Use builder pattern for complex construction
• api-extension-traits - Use extension traits to add methods to foreign types

5. Module & Visibility (MEDIUM-HIGH)

• mod-minimize-pub-api - Minimize public API surface
• mod-pub-use-reexports - Use pub use for clean module re-exports
• mod-split-large-modules - Split large modules into submodules
• mod-crate-prefix-imports - Use crate:: prefix for internal imports
• mod-tests-submodule - Use tests submodule for unit tests

6. Conversion Traits (MEDIUM)

• conv-impl-from-not-into - Implement From instead of Into
• conv-asref-for-flexibility - Accept AsRef for flexible string parameters
• conv-impl-deref-for-newtypes - Implement Deref for transparent newtype access
• conv-tryfrom-for-fallible - Use TryFrom for fallible conversions
• conv-inner-function-pattern - Use inner function pattern to reduce monomorphization

7. Idiomatic Patterns (MEDIUM)

• idiom-default-trait - Implement Default instead of new() without arguments
• idiom-constructor-naming - Follow constructor naming conventions
• idiom-let-else - Use let-else for early returns on pattern match failure
• idiom-struct-update-syntax - Use struct update syntax for partial overrides
• idiom-destructuring-assignment - Use destructuring for multiple returns and field access
• idiom-match-guards - Use match guards for complex conditions

8. Iterator & Collections (LOW-MEDIUM)

• iter-prefer-iterators-over-loops - Prefer iterator methods over manual loops
• iter-use-collect-turbofish - Use turbofish for explicit collect type
• iter-filter-map-combined - Use filter_map for combined filter and transform
• iter-avoid-collect-then-iterate - Avoid collecting then iterating
• iter-enumerate-for-indices - Use enumerate instead of manual index tracking

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Full Compiled Document

For a single-file comprehensive guide, see AGENTS.md.