Swift Refactor — Code Quality & Modernization

Comprehensive guide for refactoring Swift and SwiftUI code. Contains 42 rules across 7 categories covering API modernization, state architecture, view decomposition, navigation refactoring, architecture patterns, type safety, and Swift fundamentals.

When to Apply

Reference these guidelines when:

• Migrating from deprecated SwiftUI APIs (ObservableObject, NavigationView, old onChange)
• Restructuring state management to reduce re-renders
• Decomposing large views into maintainable components
• Refactoring navigation to use NavigationStack and NavigationPath
• Improving architecture with protocol dependencies and Environment keys
• Strengthening type safety with tagged identifiers and Result types
• Writing idiomatic Swift with proper naming, optionals, and closures

Rule Categories by Priority

Quick Reference

1. API Modernization (CRITICAL)

• api-observable-macro – Migrate ObservableObject to @Observable macro
• api-navigationstack-migration – Replace NavigationView with NavigationStack
• api-onchange-signature – Migrate to new onChange signature
• api-environment-object-removal – Replace @EnvironmentObject with @Environment
• api-alert-confirmation-dialog – Migrate Alert to confirmationDialog API
• api-list-foreach-identifiable – Replace id: .self with Identifiable conformance
• api-toolbar-migration – Replace navigationBarItems with toolbar modifier

2. State Architecture (CRITICAL)

• state-scope-minimization – Minimize state scope to nearest consumer
• state-derived-over-stored – Use computed properties over redundant @State
• state-binding-extraction – Extract @Binding to isolate child re-renders
• state-remove-observation – Remove unnecessary @ObservedObject
• state-onappear-to-task – Replace onAppear closures with .task modifier
• state-stateobject-placement – Move @StateObject to app root for shared state

3. View Decomposition (HIGH)

• view-extract-subviews – Extract subviews for composition
• view-eliminate-anyview – Replace AnyView with @ViewBuilder or generics
• view-computed-to-struct – Convert computed view properties to struct views
• view-modifier-extraction – Extract repeated modifiers into custom ViewModifiers
• view-conditional-content – Use Group or conditional modifiers over conditional views
• view-preference-keys – Replace callback closures with PreferenceKey
• view-body-complexity – Reduce view body to under 30 lines

4. Navigation Refactoring (HIGH)

• nav-centralize-destinations – Centralize navigationDestination at stack root
• nav-value-based-links – Replace destination-based NavigationLink with value-based
• nav-path-state-management – Use NavigationPath for programmatic navigation
• nav-split-view-adoption – Use NavigationSplitView for multi-column layouts
• nav-sheet-item-pattern – Replace boolean sheet triggers with item binding

5. Architecture Patterns (HIGH)

• arch-viewmodel-elimination – Eliminate unnecessary view models
• arch-protocol-dependencies – Extract protocol interfaces for external dependencies
• arch-environment-key-injection – Use Environment keys for service injection
• arch-feature-module-extraction – Extract features into independent modules
• arch-model-view-separation – Separate model logic from view code

6. Type Safety & Protocols (MEDIUM-HIGH)

• type-tagged-identifiers – Replace String IDs with tagged types
• type-result-over-optionals – Use Result type over optional with error flag
• type-phantom-types – Use phantom types for compile-time state machines
• type-force-unwrap-elimination – Eliminate force unwraps with safe alternatives

7. Swift Language Fundamentals (MEDIUM)

• swift-let-vs-var – Use let for constants, var for variables
• swift-structs-vs-classes – Prefer structs over classes
• swift-camel-case-naming – Use camelCase naming convention
• swift-string-interpolation – Use string interpolation for dynamic text
• swift-functions-clear-names – Name functions and parameters for clarity
• swift-for-in-loops – Use for-in loops for collections
• swift-optionals – Handle optionals safely with unwrapping
• swift-closures – Use closures for inline functions

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

Reference Files