swift-api-design-guidelines

# Swift API Design Guidelines

Apply the Swift API Design Guidelines when naming types, methods, properties, parameters, and argument labels. Targets Swift 6.3. For language features and syntax, see `swift-language`. For concurrency patterns, see `swift-concurrency`. For mixed requests, answer the API naming portion briefly, then route Swift type-system details to `swift-language` and lint configuration to `swiftlint` instead of implementing those sibling domains here.

## 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 these rules in order.

### When to omit the first argument label

**Grammatical phrase rule.** When the first argument forms a grammatical phrase with the base name, omit the label. Move any leading words from what would be the label into the base name instead.

```swift
// GOOD — reads as "add subview y"
view.addSubview(y)

// BAD — redundant label breaks the phrase
view.add(subview: y)
```

**Value-preserving type conversions.** When an initializer performs a value-preserving (widening) conversion, omit the first argument label.

```swift
// GOOD — widening conversion, no label
let value = Int64(someUInt32)
let str = String(someCharacter)

// Narrowing or lossy conversions keep a label
let approx = Int64(truncating: someDecimal)
let str = String(describing: someObject)
```

**Indistinguishable arguments.** When all arguments cannot be usefully distinguished, omit all labels.

```swift
// GOOD — arguments are peers
let smaller = min(x, y)
zip(sequence1, sequence2)
```

### When to use a prepositional label

**Prepositional phrase rule.** When the first argument completes a prepositional phrase with the base name, label it with the preposition.

```swift
// GOOD — "remove boxes having length 12"
x.removeBoxes(havingLength: 12)

// GOOD — "fade from red"
view.fade(from: red)

// GOOD — "relative path from root"
path.relativePath(from: root)
```

**Exception — abstraction boundary.** When the first two arguments represent parts of a single abstraction, fold the preposition into the base name so each component gets its own label.

```swift
// GOOD — x and y are parts of a single abstraction (a point)
a.moveTo(x: b, y: c)

// BAD — preposition attaches to first arg, leaving y unlabeled
a.move(toX: b, y: c)
```

### Default: label everything else

When no special rule above applies, label the argument.

```swift
// GOOD
array.split(maxSplits: 2)
button.setTitle("OK", for: .normal)
controller.dismiss(animated: true)
array.sorted(by: >)
```

### Argument label decision table

| 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)` |

For extended examples and edge cases, see [references/argument-labels-and-parameters.md](references/argument-labels-and-parameters.md).

## Side-Effect Naming

Name functions and methods by their side effects.

### Functions with side effects — imperative verbs

When a function mutates state, name it as an imperative verb phrase.

```swift
// Mutates — imperative verb
array.sort()
array.append(newElement)
list.remove(at: index)
timer.invalidate()
```

### Functions without side effects — nouns or adjective phrases

When a function returns a result without mutating anything, name it as a noun phrase, adjective phrase, or read as a description of what it returns.

```swift
// Pure — noun/description
let d = point.distance(to: origin)
let area = rect.intersection(other)
let line = text.trimmingCharacters(in: .whitespaces)
```

### Boolean properties and methods

Boolean properties and methods read as assertions about the receiver.

```swift
// GOOD — reads as "line is empty"
line.isEmpty
set.contains(element)
url.isFileURL

// BAD — not an assertion
line.empty       // verb? adjective?
set.includes     // incomplete phrase
```

For more examples, see [references/side-effects-and-mutating-pairs.md](references/side-effects-and-mutating-pairs.md).

## Mutating and Nonmutating Pairs

When an operation has both mutating and nonmutating variants, name them as a pair.

### Verb-described operations — -ed/-ing suffix

When the operation is naturally described by a verb:
- **Mutating:** imperative verb (`sort`, `append`, `reverse`)
- **Nonmutating:** past participle `-ed` or present participle `-ing`

Default to `-ed` (past participle) when the phrase naturally describes the returned value. Use `-ing` (present participle) only when the `-ed` form is ungrammatical or describes the direct object rather than the returned receiver or result. A direct object is a clue to check the grammar, not the rule by itself.

| Mutating | Nonmutating | Why |
|----------|-------------|-----|
| `sort()` | `sorted()` | `-ed` — "a sorted array" |
| `reverse()` | `reversed()` | `-ed` — "a reversed collection" |
| `sortLines()` | `sortedLines()` | `-ed` — "sorted lines" describes the result |
| `append(y)` | `appending(y)` | `-ing` — `appended` does not describe the returned receiver clearly |
| `stripNewlines()` | `strippingNewlines()` | `-ing` — direct-object pattern from the guidelin