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.