Swift Development

Swift Best Practices Skill

Overview

Apply modern Swift development best practices focusing on Swift 6+ features, concurrency safety, API design principles, and code quality guidelines for iOS and macOS projects targeting macOS 15.7+.

When to Use This Skill

Use this skill when:

• Writing new Swift code for iOS or macOS applications
• Reviewing Swift code for correctness, safety, and style
• Implementing Swift concurrency features (async/await, actors, MainActor)
• Designing Swift APIs and public interfaces
• Migrating code from Swift 5 to Swift 6
• Addressing concurrency warnings, data race issues, or compiler errors related to Sendable/isolation
• Working with modern Swift language features introduced in Swift 6 and 6.2

Core Guidelines

Fundamental Principles

1. Clarity at point of use is paramount - evaluate designs by examining use cases, not just declarations
2. Clarity over brevity - compact code comes from the type system, not minimal characters
3. Write documentation for every public declaration - if you can't describe functionality simply, the API may be poorly designed
4. Name by role, not type - var greeting = "Hello" not var string = "Hello"
5. Favour elegance through simplicity - avoid over-engineering unless complexity genuinely warrants it

Swift 6 Concurrency Model

Swift 6 enables complete concurrency checking by default with region-based isolation (SE-0414). The compiler now proves code safety, eliminating many false positives whilst catching real concurrency issues at compile time.

Critical understanding:

• Async ≠ background - async functions can suspend but don't automatically run on background threads
• Actors protect mutable shared state through automatic synchronisation
• @MainActor ensures UI-related code executes on the main thread
• Global actor-isolated types are automatically Sendable

Essential Patterns

Async/Await

// Parallel execution with async let
func fetchData() async -> (String, Int) {
    async let stringData = fetchString()
    async let intData = fetchInt()
    return await (stringData, intData)
}

// Always check cancellation in long-running operations
func process(_ items: [Item]) async throws -> [Result] {
    var results: [Result] = []
    for item in items {
        try Task.checkCancellation()
        results.append(await process(item))
    }
    return results
}

MainActor for UI Code

// Apply at type level for consistent isolation
@MainActor
class ContentViewModel: ObservableObject {
    @Published var images: [UIImage] = []

    func fetchData() async throws {
        self.images = try await fetchImages()
    }
}

// Avoid MainActor.run when direct await works
await doMainActorStuff()  // Good
await MainActor.run { doMainActorStuff() }  // Unnecessary

Actor Isolation

actor DataCache {
    private var cache: [String: Data] = [:]

    func store(_ data: Data, forKey key: String) {
        cache[key] = data  // No await needed inside actor
    }

    nonisolated func cacheType() -> String {
        return "DataCache"  // No await needed - doesn't access isolated state
    }
}

Common Pitfalls to Avoid

1. Don't mark functions as async unnecessarily - async calling convention has overhead
2. Never use DispatchSemaphore with async/await - risk of deadlock
3. Don't create stateless actors - use non-isolated async functions instead
4. Avoid split isolation - don't mix isolation domains within one type
5. Check task cancellation - long operations must check Task.checkCancellation()
6. Don't assume async means background - explicitly move work to background if needed
7. Avoid excessive context switching - group operations within same isolation domain

AppKit Gotchas

Menu-bar app windows open behind everything / hide on click-away. Two separate causes, usually hit together:

• .accessory activation policy means the app is never brought forward when a window opens.
• SwiftUI's Settings scene is an NSPanel, which in an accessory app defaults to hidesOnDeactivate = true.

Fix both: switch to .regular while the window is open, clear hidesOnDeactivate, then revert on NSWindow.willCloseNotification.

NSApp.setActivationPolicy(.regular)
NSApp.activate()
openSettings()
DispatchQueue.main.async {          // window does not exist until SwiftUI opens it
    guard let w = NSApp.windows.first(where: {
        $0.identifier?.rawValue.hasPrefix("com_apple_SwiftUI_Settings") == true }) else { return }
    w.hidesOnDeactivate = false
    w.makeKeyAndOrderFront(nil)
    w.orderFrontRegardless()
}
// On willCloseNotification: NSApp.setActivationPolicy(.accessory)

Cost: a Dock icon while the window is open. SettingsLink cannot do this - it has no action hook, so use @Environment(\.openSettings).

JSONEncoder.dateEncodingStrategy = .iso8601 truncates to whole seconds. Silently breaks any sub-second timing logic. Use .custom with ISO8601DateFormatter + .withFractionalSeconds.

API Design Quick Reference

Naming Conventions

• Types/protocols: UpperCamelCase
• Everything else: lowerCamelCase
• Protocols describing capabilities: -able, -ible, -ing suffixes (Equatable, ProgressReporting)
• Factory methods: Begin with make (x.makeIterator())
• Mutating pairs: imperative vs past participle (x.sort() / x.sorted())

Method Naming by Side Effects

• No side effects: Noun phrases (x.distance(to: y))
• With side effects: Imperative verbs (x.append(y), x.sort())