rust-idioms

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

| 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.