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 { ... }