Swift Rules

Swift Rules

These rules come from app/rules/swift/ in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Swift. Apply them when writing or reviewing Swift code.

Swift Coding Style

Naming

• PascalCase: types, protocols, enums, struct, class.
• camelCase: functions, methods, properties, variables, enum cases.
• No prefixes: Swift has module namespacing (no NS or UI prefix for your types).
• Use descriptive names: removeElement(at:) not remove(i:).
• Boolean properties read as assertions: isEmpty, hasChildren, canSubmit.

Types

• Prefer struct over class by default (value semantics, no reference cycles).
• Use class only when reference semantics or inheritance is required.
• Use enum with associated values for modeling finite states.
• Use protocol for defining capabilities. Prefer protocol composition.
• Use typealias for complex generic signatures for readability.

Optionals

• Use guard let for early exit on nil. Use if let for conditional binding.
• Never force-unwrap (!) unless failure is a programming error.
• Use ?? for default values: let name = user?.name ?? "Unknown".
• Use optional chaining: user?.address?.city.
• Use map / flatMap on optionals for transformations.

Properties

• Use let by default. Use var only when mutation is required.
• Use computed properties for derived values: var fullName: String { ... }.
• Use property observers (willSet, didSet) for side effects on change.
• Use lazy var for expensive initialization deferred until first access.
• Use @Published (Combine) for observable properties in classes.

Functions

• Use argument labels for clarity: func move(from source: Int, to destination: Int).
• Omit argument labels when the function name makes the role clear: func contains(_ element: T).
• Use default parameter values instead of multiple overloads.
• Use throws / async throws for fallible operations.
• Use trailing closure syntax for the last closure parameter.

Access Control

• Use private for implementation details. Use fileprivate sparingly.
• Use internal (default) for module-scoped access.
• Use public for framework API. Use open only when subclassing is intended.
• Prefer private(set) for read-only external access with internal mutation.

Formatting

• Use SwiftLint for automated style enforcement.
• Use SwiftFormat for automated code formatting.
• Commit .swiftlint.yml and .swiftformat to the repository.
• Max line length: 120 characters (SwiftLint default).
• Use trailing commas in multi-line arrays and dictionaries.

Swift Frameworks

SwiftUI

• Use VStack, HStack, ZStack for layout composition.
• Use List with ForEach for dynamic content. Use LazyVStack for large lists.
• Use NavigationStack (iOS 16+) with navigationDestination(for:) for type-safe navigation.
• Use .task { } modifier for async data loading tied to view lifecycle.
• Use @ViewBuilder for conditional view composition in custom containers.
• Use PreviewProvider or #Preview macro for rapid UI iteration.

UIKit (Legacy / Hybrid)

• Use UIHostingController to embed SwiftUI views in UIKit.
• Use UIViewRepresentable to wrap UIKit views in SwiftUI.
• Use Auto Layout with constraints or UIStackView for layout.
• Use UICollectionViewCompositionalLayout for complex collection layouts.
• Use Coordinator pattern for delegate-based UIKit interop in SwiftUI.

Combine

• Use Publisher / Subscriber for reactive data streams.
• Use sink for subscribing. Store cancellables in Set<AnyCancellable>.
• Use map, filter, flatMap, combineLatest for stream transformation.
• Use @Published on class properties for automatic publisher generation.
• Prefer AsyncSequence (async/await) over Combine for new code.

Swift Data

• Use @Model macro for persistent model definitions.
• Use @Query in SwiftUI views for automatic fetching and observation.
• Use ModelContext for CRUD operations: context.insert(item), context.delete(item).
• Use #Predicate macro for type-safe query filtering.
• Use ModelConfiguration for custom store locations and migration options.

Core Data (Legacy)

• Use NSPersistentContainer for stack setup.
• Use NSFetchRequest with NSPredicate for querying.
• Use performBackgroundTask for background context operations.
• Use lightweight migrations for schema changes when possible.
• Prefer SwiftData for new projects (iOS 17+).

Vapor (Server-Side)

• Use routes.get("users") for route definitions.
• Use Content protocol for request/response body codable conformance.
• Use Fluent ORM with migrations for database access.
• Use middleware for authentication, CORS, and error handling.
• Use async/await natively (Vapor 4+ is fully async).

Networking

• Use URLSession with async/await for HTTP requests.
• Use Codable with JSONDecoder for response parsing.
• Use URLCache and ETag for response caching.
• Set timeoutIntervalForRequest on URLSessionConfiguration.
• Use TaskLocal for request-scoped values (tracing, auth context).

Package Management

• Use Swift Package Manager (SPM) for dependency management.
• Define dependencies in Package.swift with exact version or version ranges.
• Use Package.resolved committed to the repository for reproducible builds.
• Prefer SPM over CocoaPods/Carthage for new projects.

Swift Patterns

Error Handling

• Use enum AppError: Error for typed, exhaustive error handling.
• Use throws functions with do-catch for recoverable errors.
• Use Result<Success, Failure> for asynchronous error propagation.
• Use try? for optional conversion. Use try! only in tests or guaranteed paths.
• Add LocalizedError conformance for user-facing error messages.

Protocol-Oriented Design

• Define capabilities as protocols: protocol Fetchable { func fetch() async throws -> Data }.
• Use protocol extensions for default implementations.
• Use protocol composition: func process(_ item: Sendable & Codable).
• Use associated types for generic protocols: associatedtype Output.
• Use some Protocol (opaque types) for return types hiding concrete implementations.

Async/Await

• Use async functions for all asynchronous operations.
• Use async let for concurrent, independent operations.
• Use TaskGroup for dynamic parallelism with collected results.
• Use Task { } to bridge sync to async. Avoid .task { } in views for complex logic.
• Use withThrowingTaskGroup for concurrent operations that can fail.

Actors

• Use actor for thread-safe mutable state (replaces manual locks).
• Use @MainActor for UI-related state and methods.
• Use nonisolated for actor methods that do not access mutable state.
• Use GlobalActor for custom isolation domains.
• Minimize await calls on actors to reduce suspension points.

SwiftUI Patterns

• Use @State for view-local mutable state.
• Use @Binding for child-to-parent state communication.
• Use @Observable (Observation framework) for model objects (preferred over @ObservedObject).
• Use @Environment for dependency injection: @Environment(\.modelContext).
• Use ViewModifier for reusable view transformations.
• Extract subviews into separate structs for readability and performance.

Codable

• Use Codable for JSON serialization/deserialization.
• Use CodingKeys enum for custom key mapping.
• Use JSONDecoder with .convertFromSnakeCase for API compatibility.
• Use @propertyWrapper for custom decoding strategies (e.g., date formats).
• Use nestedContainer for flattening nested JSON structures.

Dependency Injection

• Use initializer injection for required dependencies.
• Use @Environment in SwiftUI for framework-provided values.
• Use swift-dependencies library for testable, controlled dependency management.
• Use @Dependency(\.apiClient) var apiClient for automatic resolution.

Anti-Patterns

• Force-unwrapping optionals: use guard let or ??.
• Massive view controllers/views: split into subviews and view models.
• Reference cycles: use [weak self] in closures capturing self.
• Blocking the main thread: use Task or DispatchQueue.global().
• Stringly-typed APIs: use enums, protocols, and strong types.