/swift-api-design-guidelines

name: swift-api-design-guidelines
description: "Apply Swift API Design Guidelines to name, label, and document Swift APIs. Covers argument label rules (prepositional phrase rule, grammatical phrase rule, first-label omission), mutating/nonmutating pair naming (-ed/-ing participle pattern, form- prefix, sort/sorted, formUnion/union), side-effect naming (noun for pure, verb for mutating), documentation comment structure (summary by declaration kind, O(1) complexity rule), clarity at call site, role-based naming, protocol naming (-able/-ible/-ing), default arguments over method families, casing conventions, and terminology. Use when designing new Swift APIs, reviewing naming and argument labels, writing documentation comments, or refactoring for call site clarity."

Swift API Design Guidelines

Apply the Swift API Design Guidelines to naming, labels, documentation, and call-site clarity. For mixed requests, handle the API-design portion here and route language/type-system work to `swift-language`, concurrency to `swift-concurrency`, and lint configuration to `swiftlint`.

Contents

• [Argument Label Rules](#argument-label-rules)
• [Side-Effect Naming](#side-effect-naming)
• [Mutating and Nonmutating Pairs](#mutating-and-nonmutating-pairs)
• [Documentation Comments](#documentation-comments)
• [Clarity and Naming](#clarity-and-naming)
• [Fluent Usage and Protocols](#fluent-usage-and-protocols)
• [General Conventions](#general-conventions)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Argument Label Rules

Argument labels determine how a call site reads. Apply the first matching row:

| Situation | Rule | Example | |-----------|------|---------| | First arg completes grammatical phrase | Omit label, merge words into base name | `addSubview(y)` | | Value-preserving init conversion | Omit first label | `Int64(someUInt32)` | | Arguments are indistinguishable peers | Omit all labels | `min(x, y)` | | First arg completes prepositional phrase | Label with preposition | `fade(from: red)` | | First two args form a single abstraction | Fold preposition into base name | `moveTo(x: b, y: c)` | | Everything else | Label it | `split(maxSplits: 2)` |

Load [Argument Labels and Parameters](references/argument-labels-and-parameters.md) when resolving abstraction boundaries, multiple prepositions, conversion initializers, indistinguishable peers, parameter naming, or default arguments.

Side-Effect Naming

Use imperative verbs for operations with side effects, result-describing noun or adjective phrases for operations without side effects, and assertion-style names for Boolean APIs.

array.sort()
array.append(newElement)
let d = point.distance(to: origin)
line.isEmpty
set.contains(element)

Load [Side Effects and Mutating Pairs](references/side-effects-and-mutating-pairs.md) when reviewing extended pure/mutating examples or Boolean naming.

Mutating and Nonmutating Pairs

Name mutating/nonmutating pairs from the operation's natural description:

• For verb operations, use the imperative for mutation and a result-describing

participle for the copy: `sort()/sorted()` or `append(_:)/appending(_:)`. Prefer `-ed`; use `-ing` only when `-ed` is ungrammatical or describes the direct object instead of the returned result.

• For noun operations, use the noun for the copy and `form` + noun for

mutation: `union(_:)` / `formUnion(_:)`.

• Prefix factories that create new values with `make`.

Load the [`-ed`/`-ing` Decision Tree](references/side-effects-and-mutating-pairs.md#the--ed-ing-decision-tree) when the returned-result grammar is unclear. The same reference contains expanded `form`-prefix, Boolean, and factory patterns.

Documentation Comments

Every public declaration must have a documentation comment.

Summary rules by declaration kind

| Declaration | Summary describes | |-------------|-------------------| | Function / method | What it does and what it returns | | Subscript | What it accesses | | Initializer | What it creates | | Type / property / variable | What it **is** |

Write summaries as a single sentence fragment, beginning with a verb (for actions) or a noun phrase (for entities), ending in a period.

/// Returns the element at the specified index.
func element(at index: Int) -> Element { ... }

/// The number of elements in the collection.
var count: Int { ... }

/// Creates a new array with the given elements.
init(_ elements: some Sequence<Element>) { ... }

/// Accesses the element at the specified position.
subscript(index: Int) -> Element { ... }

Symbol markup

Use standard symbol markup after the summary when relevant:

• `- Parameter name:` for individual parameters
• `- Parameters:` block for multiple parameters
• `- Returns:` for the return value
• `- Throws:` for errors thrown
• `- Complexity:` for algorithmic complexity

/// Removes and returns the element at the specified position.
///
/// - Parameter index: The position of the element to remove.
/// - Returns: The removed element.
/// - Complexity: O(*n*), where *n* is the length of the collection.
mutating func remove(at index: Int) -> Element { ... }

O(1) complexity rule

Document the complexity of any computed property that is not O(1). Callers assume properties are O(1) by default. If a property does more than constant-time work, state the complexity explicitly.

/// The total weight of all items.
///
/// - Complexity: O(*n*), where *n* is the number of items.
var totalWeight: Double {
    items.reduce(0) { $0 + $1.weight }
}

For documentation patterns and examples, see [references/conventions-and-special-rules.md](references/conventions-and-special-rules.md).

Clarity and Naming

Clarity at the point of use is the most important goal. Every design decision serves the person reading a call site.

**Clarity over brevity.** Longer names are acceptable when they remove ambiguity.