Swift Idioms

Swift Idioms and Patterns

Swift rewards value types, optionals, and protocol-oriented design. Idiomatic Swift = safe, expressive, Swifty.

Scope: Swift coding idioms. Test naming: .agents/rules/testing-strategy.md.

Value Types and Optionals

1. Prefer structs over classes — value semantics by default. Classes only for identity, inheritance, or reference counting.

2. Optionals — never force-unwrap (!) in production:

   // ✅ Guard let for early exit
   guard let task = storage.findById(id) else {
       throw TaskError.notFound(id)
   }
   
   // ✅ Optional chaining
   let title = task?.title ?? "Untitled"
   
   // ✅ if let for conditional binding
   if let deadline = task.deadline {
       scheduleReminder(for: deadline)
   }
   
   // ❌ Force unwrap — crash risk
   let task = storage.findById(id)!

3. Property wrappers for reusable behavior:

   @propertyWrapper
   struct Clamped<Value: Comparable> {
       var wrappedValue: Value {
           didSet { wrappedValue = min(max(wrappedValue, range.lowerBound), range.upperBound) }
       }
       let range: ClosedRange<Value>
   
       init(wrappedValue: Value, _ range: ClosedRange<Value>) {
           self.range = range
           self.wrappedValue = min(max(wrappedValue, range.lowerBound), range.upperBound)
       }
   }
   
   struct Task {
       @Clamped(0...100) var progress: Int = 0
   }

Error Handling

For universal error handling principles, see .agents/rules/error-handling-principles.md.

1. Typed throws (Swift 6) or Error protocol:

   enum TaskError: Error, LocalizedError {
       case notFound(String)
       case validationFailed(field: String, message: String)
       case storageUnavailable
   
       var errorDescription: String? {
           switch self {
           case .notFound(let id): "Task '\(id)' not found"
           case .validationFailed(let field, let msg): "Validation failed on \(field): \(msg)"
           case .storageUnavailable: "Storage is unavailable"
           }
       }
   }
   
   func getTask(id: String) throws(TaskError) -> Task { ... }

2. Result type for async callbacks (pre-async/await):

   func fetchTask(id: String) async -> Result<Task, TaskError> { ... }

3. do/catch with pattern matching:

   do {
       let task = try getTask(id: "123")
       process(task)
   } catch TaskError.notFound(let id) {
       logger.warn("Task not found", metadata: ["taskId": id])
   } catch {
       logger.error("Unexpected error", metadata: ["error": "\(error)"])
   }

4. defer for cleanup:

   func processFile(at path: String) throws -> Data {
       let handle = try FileHandle(forReadingFrom: URL(fileURLWithPath: path))
       defer { handle.closeFile() }  // ✅ Always runs on exit
   
       return handle.readDataToEndOfFile()
   }

Protocol-Oriented Design

1. Protocols over abstract classes:

   // ✅ Interface defined as protocol
   protocol TaskStorage {
       func getById(_ id: String) async throws -> Task?
       func save(_ task: Task) async throws
   }
   
   // ✅ Production implementation
   struct PostgresTaskStorage: TaskStorage {
       let pool: ConnectionPool
   
       func getById(_ id: String) async throws -> Task? {
           try await pool.query("SELECT * FROM tasks WHERE id = $1", [id]).first
       }
   
       func save(_ task: Task) async throws {
           try await pool.execute("INSERT INTO tasks ...", [task.id, task.title])
       }
   }
   
   // ✅ Test implementation
   struct MockTaskStorage: TaskStorage {
       var tasks: [Task] = []
   
       func getById(_ id: String) async throws -> Task? {
           tasks.first { $0.id == id }
       }
   
       func save(_ task: Task) async throws {
           tasks.append(task)
       }
   }

2. Protocol extensions for default implementations:

   protocol Identifiable {
       var id: String { get }
   }
   
   extension Identifiable {
       var isNew: Bool { id.isEmpty }
   }

3. Associated types for generic protocols:

   protocol Repository {
       associatedtype Entity
       func findById(_ id: String) async throws -> Entity?
       func save(_ entity: Entity) async throws
   }