Swift Programmer

Swift Programming

This skill covers Swift-specific idioms, tooling, and philosophy for both application development and command-line scripting. It emphasizes protocol-oriented programming, value semantics, strict concurrency (Swift 6+), and compile-time safety guarantees.

Core Philosophy

Let the compiler carry the safety argument. Swift 6 adds compile-time data-race safety to memory safety, so design so that the checker can prove the code correct rather than suppressing its diagnostics; the working model for that — isolation domains rather than threads — is developed in <concurrency_fundamentals>.

Prefer protocol composition over inheritance, value semantics over reference semantics, and static dispatch over dynamic dispatch.

Version targeting: Use the latest Swift version available. For internal apps, target only the current version. For open-source libraries, support at most the current version and one or two prior ones.

Swift 6 Concurrency

Prefer structured concurrency. Child tasks (async let, TaskGroup) inherit their parent's priority and cancellation and cannot outlive it. SE-0304 frames unstructured tasks — both Task { } and Task.detached — as the escape valve for work "whose lifetime is not bound to the creating task, for example in order to fire-and-forget some operation or to initiate asynchronous work from synchronous code."[^se-0304] The two differ in what they inherit: Task.detached inherits no actor isolation, priority, or task-local values, whereas Task { } inherits all three.[^tspl] Use Task { } for unstructured work that should keep its context, and Task.detached only when independence from that context is the point.

Approachable Concurrency (opt-in, Swift 6.2+)[^approachable-concurrency]: a configuration pairing SE-0461's caller's-actor default for nonisolated async functions[^se-0461] with SE-0466's default @MainActor inference.[^se-0466] Under it, unannotated code is inferred @MainActor and a nonisolated async function runs on whichever actor called it, so code that doesn't opt into parallelism runs sequentially and most data-race errors for naturally sequential code disappear. Parallelism still enters where you ask for it — @concurrent, Task.detached, a custom actor, or a concurrent API — and only the unannotated and nonisolated async cases change; explicitly isolated code behaves as before. Apple states that main-actor mode "is enabled by default for new app projects created with Xcode 26";[^wwdc25-268] existing targets and bare -swift-version 6 builds do not enable it, and swift package init generates a manifest with the Swift 6 language mode but neither setting (observed with Swift 6.3.2; check the generated Package.swift on your toolchain). Check the target's settings before assuming either execution behavior.

Choosing an Isolation Strategy

Prefer @MainActor over a custom actor for anything SwiftUI observes: views run on the main actor and would need an await to read a custom actor's state, which is exactly the friction main-actor isolation removes.

Actor Re-entrancy

actor OrderQueue {
    var pending: [Order] = []
    var inFlight: Set<Order.ID> = []

    func processNext() async {
        guard let order = pending.first(where: { !inFlight.contains($0.id) }) else { return }
        inFlight.insert(order.id)               // claim before suspending: a second caller cannot pick the same order
        await perform(order)                    // other tasks may run here and mutate `pending`
        inFlight.remove(order.id)
        if let i = pending.firstIndex(where: { $0.id == order.id }) {
            pending.remove(at: i)               // re-validate: `pending` may have changed across the await
        }                                       // claim, and check-and-remove, each contain no `await`, so neither can be interleaved
    }
}

The claim is what prevents duplicate work: without inFlight, two callers suspended in perform would both have read the same first element. Keep actor methods synchronous where you can and compose async wrappers around them; a synchronous actor method cannot be interleaved.

@MainActor Guarantees

Two Swift 6.2 additions reduce how much annotation main-actor code needs:

• Isolated conformances — a conformance that needs main-actor state is written extension Model: @MainActor Exportable, and the compiler then permits its use only from main-actor contexts.[^apple-concurrency-updates]
• Default main-actor mode — -default-isolation MainActor infers @MainActor on declarations project-wide; opt individual functions out with nonisolated or @concurrent.[^se-0466]

Mark a method nonisolated when it touches no main-actor state and must be callable from anywhere; the compiler enforces that it accesses no isolated state. In the Swift 6 language mode Thread.isMainThread is unavailable from async contexts — the compiler steers you toward @MainActor annotations rather than thread checks.

Sendable

Implicit conformance is narrow: Apple's Sendable documentation grants it to structures and enumerations that qualify and are either frozen or non-public and not @usableFromInline, and SE-0316 grants it to any non-protocol type annotated with a global actor (e.g., a @MainActor class),[^se-0316] with SE-0434's qualifications: a global-actor-isolated subclass of a non-Sendable superclass is not Sendable, and a global-actor-isolated closure may capture non-Sendable values even though it is @Sendable, because it can never run concurrently with itself.[^se-0434] Other classes, and public non-frozen value types without global-actor isolation, declare the conformance explicitly. A @Sendable closure that needs a mutable variable's current value captures it by value in the capture list ({ [count] in … }).[^apple-diagnostics]

Escape hatches, in order of preference. The migration guide's rule is that "if a type isn't already thread-safe, attempting to make it Sendable should not be your first approach";[^migration-common-problems] reach for an actor or @MainActor first. When a type genuinely does its own synchronization, prefer a form the compiler can check: Mutex from the Synchronization module is itself Sendable,[^se-0433] so a final class whose state lives entirely in let Mutex properties conforms to Sendable with checking intact. Reserve @unchecked Sendable for synchronization the compiler cannot see (e.g., a lock guarding a var), and document the invariant it relies on. For a single variable guarded by an external lock or queue, nonisolated(unsafe) opts that one declaration out of checking; the guide restricts it to cases where "you are carefully guarding all access to the variable with an external synchronization mechanism."[^migration-common-problems]

Region-Based Isolation and sending

Offloading Work with @concurrent

Apple's recipe for offloading a function:[^apple-concurrency-updates] add @concurrent to the function (which makes that function nonisolated), make it async if it isn't already, and await it at call sites; Apple's worked example also marks the enclosing type nonisolated, but do that only when none of the type's members need actor isolation, because SE-0461 permits @concurrent methods inside actors and @MainActor types.[^se-0461] Apply it to CPU-intensive work (e.g., image or video processing, large parses) that would otherwise stall the calling actor; I/O that suspends rather than blocks gains nothing from it, unless the same function also does substantial synchronous work after the await (e.g., decoding a large response), in which case that work is what you offload. Before the feature is enabled, nonisolated(nonsending) gives an individual function the caller's-actor behavior, and the migration flag -enable-upcoming-feature NonisolatedNonsendingByDefault:migrate adds @concurrent to existing nonisolated async functions so their semantics don't change silently.[^apple-nonisolated-nonsending]

Migrating to Strict Concurrency

The :migrate variant of an upcoming-feature flag adds fix-its that preserve existing behavior while you adopt the feature.[^apple-nonisolated-nonsending]

Protocol-Oriented Programming

When to use protocols:

• Multiple types share behavior without sharing state
• Value types need to participate
• Multiple conformance needed (Swift = single inheritance for classes)
• Retroactive conformance to types you don't own

When to use classes:

• Need stored property inheritance
• Need to call super implementations
• Working with UIKit/AppKit (forced)
• Identity matters more than equality

Protocol extensions = mixins: Default implementations enable code reuse without inheritance.

Anti-pattern from OOP: Treating protocols as "interfaces" with no default implementations. This recreates OOP hierarchy problems.

Dispatch rule: a method declared only in a protocol extension is statically dispatched on the compile-time type; a method that is also a protocol requirement is dynamically dispatched to the conforming type's implementation. Declare a requirement whenever conformers are expected to override.

Value vs Reference Types

Decision tree:

Need identity semantics (object lifetime matters)? → class
Need shared mutable state? → class, or an actor when that state crosses isolation domains
Subclassing an Objective-C framework class, or passing data to an Objective-C API? → class
Need stored property inheritance? → class
Everything else → struct

Performance: a value type whose stored properties are themselves reference-free needs no heap allocation or reference counting of its own, and small ones pass in registers, so do not choose a class on the assumption that pointer semantics are cheaper; a large value, or one holding references, pays copying or retain/release costs that the optimizer may or may not remove.

Know what a stored class reference does to a value type: copies of the struct share that object, so the field has reference semantics unless the type implements copy-on-write (the standard library's technique for its collections), and each copy retains it (the optimizer removes some retain/release pairs, but design as if it didn't). Keep value types free of inner references where the field's semantics don't call for sharing; use copy-on-write when they need a shared buffer with value semantics.

Error Handling

Swift 6 typed throws:

enum FileError: Error { case notFound, unreadable(any Error) }

func loadFile(_ path: String) throws(FileError) -> Data {
    guard fileExists(path) else { throw .notFound }
    do { return try Data(contentsOf: URL(fileURLWithPath: path)) }
    catch { throw .unreadable(error) }        // a typed-throws body cannot propagate `any Error` unchanged
}
// Caller: error is FileError, not 'any Error'

Tooling

Swift Package Manager: Three-layer architecture (Core ← Domain ← Features). Unidirectional dependencies.

Testing: Prefer Swift Testing for new unit tests (native async, #expect macro, parameterized tests). Apple's guidance is to "continue using XCTest for any tests which use UI automation APIs like XCUIApplication or use performance testing APIs like XCTMetric as these are not supported in Swift Testing."[^wwdc24-10179]

Documentation: document every public API with DocC, using ​``Symbol``​ links, and state algorithmic complexity when it is not O(1).

Configuration files: See local .swiftlint.yml and .swiftformat in projects for standard configs.

Swift Scripting

Use Swift for shell scripting when a script needs what Swift uniquely offers — on macOS, that is direct calls into Foundation, AppKit, and other platform frameworks from a command-line tool without a full app project. Compared to Python or Ruby, Swift trades startup latency for type safety and direct framework access.

Choosing Swift for a Script

Script Essentials

Start every script with #!/usr/bin/env -S swift -swift-version 6. Language modes are opt-in — Apple's error-in-future-swift-version.md states that code "will not build with the new language mode until you set that language mode in your build settings"[^apple-diagnostics] — so plain swift script.swift runs in the Swift 5 language mode and silently lacks the strict data-race checking described in <concurrency_fundamentals> until -swift-version 6 is passed.

Write top-level statements. Top-level code is the script's entry point, and it supports await directly — call async APIs in straight-line code rather than wrapping them in semaphores or run-loop spins, and reserve RunLoop.main.run() for callback- and notification-based APIs that never complete. @main is forbidden in a file that allows top-level statements, which is what the swift interpreter compiles; an explicit @main entry point requires compiling, via swiftc -parse-as-library or an SPM executable target.[^scripting-main-forbidden] (The interpreter rejects -parse-as-library; observed with Swift 6.3.2.)

Convert to an SPM executable when a script needs a dependency or a test, rather than reaching for scripting tooling.

For shebang variants (Xcode build phases, systems whose env lacks -S), argument handling, Linux compatibility of Foundation and the platform frameworks, recompile-per-run latency, and the narrow case for swift-sh, read references/swift-scripting.md.

Common Mistakes from Other Languages

Memory Management Gotchas

Closure capture lists:

{ [weak self] in
    guard let self else { return }
    // Use self
}

Weak vs Unowned:

• weak: Optional, auto-nil when deallocated (safe)
• unowned: not cleared on deallocation (traps if accessed afterwards); may be optional, in which case you keep it valid yourself[^tspl]

Rule: Prefer weak unless the referenced object is guaranteed to outlive the reference.

Core Foundation and C boundaries: when an imported signature returns Unmanaged<T>, Swift lacks the ownership annotation and you must apply the Create/Copy-versus-Get rule yourself; getting it backwards over-releases or leaks. Read references/core-foundation-interop.md before writing that conversion, and for @convention(c), dlsym, and container lifetimes.

API Design Core Principles

Naming:

• No side-effects → noun phrases: x.distance(to: y)
• With side-effects → imperative verbs: x.sort()
• Mutating/non-mutating pairs: sort()/sorted(), append(_:)/appending(_:)
• Factory methods start with "make": makeIterator()

Access control: Default to private, use internal for module-wide, public/open only for framework APIs.

Source: https://www.swift.org/documentation/api-design-guidelines/

Recent Changes

Additions, by release:

• Swift 6.1 (March 31, 2025)[^swift-61]: nonisolated on types and extensions to prevent @MainActor inference; inferred child-task result types for withTaskGroup; @implementation for supplying Swift implementations of Objective-C declarations; trailing commas in more positions (e.g., tuples, parameter lists, capture lists); package traits; Swift Testing's TestScoping trait protocol (ST-0007) and #expect(throws:) returning the caught error (ST-0006).
• Swift 6.2 (September 15, 2025)[^swift-62]: the concurrency changes developed in <concurrency_fundamentals> and <offloading_with_concurrent> (default main-actor isolation, caller's-actor nonisolated async as an upcoming feature, @concurrent); InlineArray and Span; opt-in strict memory safety that flags unsafe constructs; the Subprocess package for launching processes with Swift concurrency; a typed NotificationCenter API and the Observations async sequence; Swift Testing exit tests and attachments; and migration tooling for upcoming features (the :migrate flag variant[^apple-nonisolated-nonsending]).
• Swift 6.3 (March 24, 2026)[^swift-63]: @c to "expose Swift functions and enums to C code"; module selectors to "specify which imported module Swift should look in for an API"; and performance-control attributes giving library authors "finer-grained control over compiler optimizations for clients of their APIs." Read the release post before using any of the three.
• Swift 6.4 (next release; Embedded Swift improvements have been announced for it).[^swift-aug-2026] Accepted for a future release and not yet tied to a version: SE-0516 Iterable and SE-0544 (mutation and consumption in non-copyable deinits).[^swift-aug-2026] Check the swift.org blog for what has landed.

Behavior changes, deprecations, and things being moved away from:

• nonisolated async execution semantics changed under SE-0461: with NonisolatedNonsendingByDefault enabled, such a function runs on the caller's actor instead of the concurrent pool. Code written to the old semantics needs @concurrent to keep offloading; see <offloading_with_concurrent>.[^se-0461]
• Swift 6.3.2 concurrency regression (Xcode 26.5 known issue): a closure with explicit captures passed to a nonisolated(nonsending) parameter has its isolation inferred from the parent context rather than set to nonisolated(nonsending), and an actor-hop fix in 6.3.2 made the difference observable, so synchronous code after the await can run off the main actor. Apple's workarounds are to drop the explicit capture list or to use a local function declared nonisolated(nonsending). Affects projects with NonisolatedNonsendingByDefault enabled.[^xcode-26-5]
• @_cdecl is superseded. SE-0495 (Swift 6.3) "aims to formalize and extend the long experimental @_cdecl" as @c; use @c in new code. Switching an existing declaration is an ABI break because @_cdecl emits two symbols, so leave shipped ABI alone.[^se-0495]
• Community style guides: the Kodeco Swift style guide has had no commits since April 2025 (checked September 2026; see <resources>). That establishes inactivity, not abandonment or a community move away; read the guide as a snapshot of conventions as of April 2025.

Respecting Third-Party Codebases

Local Documentation Resources

Swift Diagnostic Docs (one file per compiler diagnostic):

• Path: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/doc/swift/diagnostics/
• Files: sendable-closure-captures.md, actor-isolated-call.md, and some forty others (46 in Xcode 26)
• Use when: a Swift 6 concurrency error names a diagnostic; the file explains the cause and the sanctioned fixes

Framework and Language Guides:

• Path: /Applications/Xcode.app/Contents/PlugIns/IDEIntelligenceChat.framework/Versions/A/Resources/AdditionalDocumentation/
• Files: Swift-Concurrency-Updates.md, Swift-InlineArray-Span.md, and framework guides (e.g., SwiftUI, AppKit, Foundation updates)
• Use when: working with Swift 6.2+ language features or the frameworks those guides cover

The Swift Programming Language Book:

• Online: https://docs.swift.org/swift-book/
• Source (Markdown): https://github.com/swiftlang/swift-book/tree/main/TSPL.docc
• Use when: Need authoritative language reference

Authoritative Resources

Tooling:

• SwiftLint: https://github.com/realm/SwiftLint
• SwiftFormat: https://github.com/nicklockwood/SwiftFormat
• Swift Testing: https://github.com/swiftlang/swift-testing

Scripting:

• swift-argument-parser: https://github.com/apple/swift-argument-parser
• swift-sh (personal scripts only; introduces external dependency): https://github.com/mxcl/swift-sh

Style Guides:

• Google: https://google.github.io/swift/
• Kodeco: https://github.com/kodecocodes/swift-style-guide (no commits since April 2025, as of September 2026)

Sources

[^api-guidelines]: Apple Inc. Swift API Design Guidelines. https://www.swift.org/documentation/api-design-guidelines/

[^value-semantics]: Apple Inc. Choosing Between Structures and Classes. Swift Documentation. Retrieved September 4, 2026 from https://developer.apple.com/documentation/swift/choosing-between-structures-and-classes

[^approachable-concurrency]: Swift Project. 2025. Approachable Concurrency Vision Document. Swift Evolution. https://github.com/swiftlang/swift-evolution/blob/main/visions/approachable-concurrency.md

[^se-0414]: Michael Gottesman, et al. 2024. SE-0414: Region-based Isolation. Swift Evolution. https://github.com/swiftlang/swift-evolution/blob/main/proposals/0414-region-based-isolation.md

[^se-0430]: Michael Gottesman, et al. 2024. SE-0430: sending parameter and result values. Swift Evolution. https://github.com/swiftlang/swift-evolution/blob/main/proposals/0430-transferring-parameters-and-results.md

[^se-0461]: Holly Borla, et al. 2025. SE-0461: Run nonisolated async functions on the caller's actor by default. Swift Evolution. https://github.com/swiftlang/swift-evolution/blob/main/proposals/0461-async-function-isolation.md

[^se-0466]: Holly Borla and Doug Gregor. 2025. SE-0466: Control default actor isolation inference. Swift Evolution. Retrieved August 31, 2026 from https://github.com/swiftlang/swift-evolution/blob/main/proposals/0466-control-default-actor-isolation.md

[^swift-61]: Holly Borla. 2025. Swift 6.1 Released (March 31, 2025). Swift.org Blog. Retrieved September 5, 2026 from https://www.swift.org/blog/swift-6.1-released/

[^swift-62]: Holly Borla. 2025. Swift 6.2 Released (September 15, 2025). Swift.org Blog. Retrieved September 5, 2026 from https://www.swift.org/blog/swift-6.2-released/

[^se-0495]: Alexis Laferrière. 2025. SE-0495: C compatible functions and enums. Swift Evolution; status "Implemented (Swift 6.3)". Retrieved September 5, 2026 from https://github.com/swiftlang/swift-evolution/blob/main/proposals/0495-cdecl.md

[^swift-63]: Holly Borla and Joe Heck. 2026. Swift 6.3 Released (March 24, 2026). Swift.org Blog. Retrieved September 5, 2026 from https://www.swift.org/blog/swift-6.3-released/

[^swift-aug-2026]: Simon Leeb and Dave Lester. 2026. What's new in Swift: August 2026 Edition (September 4, 2026). Swift.org Blog. Retrieved September 5, 2026 from https://www.swift.org/blog/whats-new-in-swift-august-2026/

[^xcode-26-5]: Apple Inc. 2026. Xcode 26.5 Release Notes, section "Swift > Known Issues" (issue 176582055). Retrieved September 5, 2026 from https://developer.apple.com/documentation/xcode-release-notes/xcode-26_5-release-notes

[^claude-models]: Anthropic. 2026. Models overview, "Compare models" table, row "Reliable knowledge cutoff." Claude API Documentation. Retrieved September 5, 2026 from https://platform.claude.com/docs/en/models/overview

[^tspl]: Apple Inc. and Swift Project Authors. 2014–2025. The Swift Programming Language. https://docs.swift.org/swift-book/

[^scripting-main-forbidden]: Swift Forums. 2023. @main in a single Swift file? Retrieved May 8, 2026 from https://forums.swift.org/t/main-in-a-single-swift-file/63079

[^scripting-swift-install-linux]: Swift Project. 2026. Install Swift - Linux. Swift.org. Retrieved June 21, 2026 from https://www.swift.org/install/linux/

[^se-0304]: John McCall, Joe Groff, Doug Gregor, and Konrad Malawski. 2021. SE-0304: Structured Concurrency. Swift Evolution. Retrieved September 1, 2026 from https://github.com/swiftlang/swift-evolution/blob/main/proposals/0304-structured-concurrency.md

[^se-0306]: John McCall, Doug Gregor, Konrad Malawski, and Chris Lattner. 2021. SE-0306: Actors. Swift Evolution. Retrieved September 1, 2026 from https://github.com/swiftlang/swift-evolution/blob/main/proposals/0306-actors.md

[^se-0316]: John McCall and Doug Gregor. 2021. SE-0316: Global actors, section "Using global actors on a type." Swift Evolution. Retrieved September 5, 2026 from https://github.com/swiftlang/swift-evolution/blob/main/proposals/0316-global-actors.md

[^apple-sendable]: Apple Inc. Sendable, sections "Sendable Structures and Enumerations" and "Sendable Classes." Swift Standard Library Documentation. Retrieved September 5, 2026 from https://developer.apple.com/documentation/swift/sendable

[^se-0433]: Alejandro Alonso. 2024. SE-0433: Synchronous Mutual Exclusion Lock, section "Interactions with Swift Concurrency." Swift Evolution. Retrieved September 5, 2026 from https://github.com/swiftlang/swift-evolution/blob/main/proposals/0433-mutex.md

[^se-0337]: Doug Gregor and Becca Royal-Gordon. 2022. SE-0337: Incremental migration to concurrency checking. Swift Evolution. Retrieved September 5, 2026 from https://github.com/swiftlang/swift-evolution/blob/main/proposals/0337-support-incremental-migration-to-concurrency-checking.md

[^se-0423]: Holly Borla and Pavel Yaskevich. 2024. SE-0423: Dynamic actor isolation enforcement from non-strict-concurrency contexts. Swift Evolution. Retrieved September 5, 2026 from https://github.com/swiftlang/swift-evolution/blob/main/proposals/0423-dynamic-actor-isolation.md

[^se-0434]: Sima Nerush, Matt Massicotte, and Holly Borla. 2024. SE-0434: Usability of global-actor-isolated types. Swift Evolution. Retrieved September 5, 2026 from https://github.com/swiftlang/swift-evolution/blob/main/proposals/0434-global-actor-isolated-types-usability.md

[^se-0412]: John McCall and Sophia Poirier. 2023. SE-0412: Strict Concurrency for Global Variables. Swift Evolution. Retrieved September 1, 2026 from https://github.com/swiftlang/swift-evolution/blob/main/proposals/0412-strict-concurrency-for-global-variables.md

[^wwdc25-268]: Apple Inc. 2025. Embracing Swift concurrency (WWDC25 session 268), session transcript. Retrieved September 4, 2026 from https://developer.apple.com/videos/play/wwdc2025/268/

[^wwdc24-10179]: Apple Inc. 2024. Meet Swift Testing (WWDC24 session 10179), session transcript. Retrieved September 5, 2026 from https://developer.apple.com/videos/play/wwdc2024/10179/

[^wwdc21-10133]: Apple Inc. 2021. Protect mutable state with Swift actor

…(truncated)