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

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.