swift-development

Files (5)

• SKILL.md
• api-design.md · references/
• availability-patterns.md · references/
• concurrency.md · references/
• swift6-features.md · references/

SKILL.md (first lines)

# 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
```swift
// 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
```swift
// 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
```swift
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`.

```swift
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)

From sammcj/agentic-coding, Apache-2.0.

More from sammcj/agentic-coding