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.