Production-grade Swift code quality patterns drawn from analysis of 75+ top-rated open-source Swift projects, including CotEditor, realm/SwiftLint, nikitabobko/AeroSpace, sindresorhus/Gifski, exelban/stats, and pointfreeco/swift-composable-architecture.
How to Use
- Determine the platform — macOS, iOS, or both?
- Read the relevant references based on the task
- Apply patterns when writing or reviewing code
Reference Routing
Read only what the task requires — do not load everything at once.
| File | When to Read |
|---|---|
references/shared-swift.md |
Always read first. Core Swift patterns: naming, concurrency, error handling, generics, memory management, Codable, @Observable. |
references/airbnb-style-rules.md |
Read when writing any Swift code. Complete Airbnb style rules with WRONG/RIGHT examples, file organization, SwiftUI patterns, testing rules, and copy-paste SwiftLint/SwiftFormat configs. |
references/macos-patterns.md |
When building a macOS app. AppKit, SwiftUI for Mac, menu bar apps, IOKit/SMC system APIs, Sparkle auto-updates, sandboxing, distribution. |
references/ios-patterns.md |
When building an iOS app. SwiftUI navigation, SwiftData, StoreKit 2, WidgetKit, push notifications, background tasks, accessibility. |
references/architecture.md |
When designing app structure. TCA, MVVM with @Observable, swift-dependencies DI, module structure, multi-platform architecture. |
references/tooling-setup.md |
When setting up a project. SwiftLint config, SwiftFormat config, periphery dead-code detection, GitHub Actions CI, Xcode project structure. |
references/testing.md |
When writing tests. XCTest, Swift Testing (@Test), snapshot testing, mockolo/@Spyable mocking, TCA TestStore, UI testing. |
Quick Decisions
Project Setup (read tooling-setup.md)
- Use SwiftLint + SwiftFormat from day one
- Prefer Swift Package Manager over CocoaPods/Carthage
- Set up CI with
peripheryfor dead code detection - Use
.editorconfigfor consistent whitespace
Architecture (read architecture.md)
- Small apps: MVVM with
@Observable - Medium apps: MVVM + Coordinator + dependency injection via
swift-dependencies - Large apps: TCA (The Composable Architecture) for full testability
- Multi-platform: Shared/ + Mac/ + iOS/ module structure (NetNewsWire pattern)
Platform-Specific
- macOS (read
macos-patterns.md): AppKit for system-level, SwiftUI for UI. Sparkle for updates. Handle sandboxing. - iOS (read
ios-patterns.md): SwiftUI-first with UIKit for advanced needs. Handle lifecycle, background tasks, push notifications.
Testing (read testing.md)
- XCTest for unit tests (built-in, no dependencies)
swift-snapshot-testingfor UI regressionswift-custom-dumpfor better assertion messagesmockoloor@Spyablemacro for mock generation
Universal Principles
Apply to every Swift file, regardless of platform:
- Prefer value types (structs, enums) over classes unless you need identity or inheritance
- Use Swift concurrency (async/await, actors) instead of GCD or Combine for new code
- Make illegal states unrepresentable — use enums with associated values
- Protocol-oriented design — define behavior via protocols, not inheritance
- Minimize optionals — use non-optional types when the value is always present
- Access control matters — default to
private, expose only what's needed - Name things clearly — follow Apple's API Design Guidelines (clarity > brevity)
- Keep files focused — one type per file, max ~300 lines
- Default classes to
final— composition over inheritance - No
print()in production — useos_logorswift-log
Anti-Patterns
- Massive view controllers/views — break into smaller components
- Force unwrapping (
!) outside ofIBOutlet— useguard letorif let - Stringly-typed code — use enums, not raw strings for keys/identifiers
- Ignoring errors — handle every
throwsexplicitly, don't usetry?lazily - God objects — no single type should handle networking, persistence, AND UI
- Premature abstraction — don't create protocols for things with one conformer
- Combine for new code — prefer Swift concurrency; Combine is being superseded
@unchecked Sendable— useSendable,@MainActor, or@preconcurrency importinstead