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

Argument Label Rules
Side-Effect Naming
Mutating and Nonmutating Pairs
Documentation Comments
Clarity and Naming
Fluent Usage and Protocols
General Conventions
Common Mistakes
Review Checklist
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.

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.

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

-ed

is ungrammatical — typically when the verb does not form a natural past participle, or when adding

-ed

produces an awkward phrase — use

-ing

(present participle) instead.

Mutating	Nonmutating	Why
`sort()`	`sorted()`	`-ed` — "a sorted array"
`reverse()`	`reversed()`	`-ed` — "a reversed collection"
`append(y)`	`appending(y)`	`-ing` — "appended" is ungrammatical here
`stripNewlines()`	`strippingNewlines()`	`-ing` — "stripped newlines" is awkward

Noun-described operations — form- prefix

When the operation is naturally described by a noun:

Nonmutating: the noun itself (
```
union
```
,
```
intersection
```
)
Mutating:
```
form
```
prefix (
```
formUnion
```
,
```
formIntersection
```
)

swift

// Nonmutating — returns new value
let combined = a.union(b)

// Mutating — modifies in place
a.formUnion(b)

Factory methods — make- prefix

Factory methods that create a new value start with

make

swift

let iterator = collection.makeIterator()
let buffer = parser.makeBuffer()

Pair decision table

Operation described by	Mutating name	Nonmutating name	Example pair
Verb (default)	verb	verb + `-ed`	`sort()` / `sorted()`
Verb ( `-ed` is ungrammatical)	verb	verb + `-ing`	`stripNewlines()` / `strippingNewlines()`
Noun	`form` + Noun	noun	`formUnion(b)` / `union(b)`

For the full -ed/-ing decision tree and stdlib examples, see references/side-effects-and-mutating-pairs.md.

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.

swift

/// 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

swift

/// 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.

swift

/// 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.

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. Do not abbreviate.

swift

// GOOD
employees.remove(at: position)

// BAD — ambiguous: remove the element? remove at position?
employees.remove(position)

Include words needed to avoid ambiguity. If omitting a word makes the call site unclear, keep it.

swift

// GOOD — "at" clarifies the argument's role
friends.remove(at: index)

// BAD — is "index" the element to remove or the position?
friends.remove(index)

Omit needless words. Do not repeat type information already available from the context.

swift

// GOOD
allViews.remove(cancelButton)

// BAD — "Element" repeats the type
allViews.removeElement(cancelButton)

Name variables and parameters by role, not type. Use the entity's role in the current context, not its type name.

swift

// GOOD — describes the role
var greeting: String
func add(_ observer: NSObject, for keyPath: String)

// BAD — names the type
var string: String
func add(_ object: NSObject, for string: String)

Compensate for weak type information. When a parameter type is

Any

AnyObject

, or a fundamental type like

Int

String

, add role-clarifying words to the name.

swift

// GOOD — role is clear despite weak types
func addObserver(_ observer: NSObject, forKeyPath path: String)

// BAD — what does "string" mean here?
func add(_ object: NSObject, for string: String)

For extended naming examples and patterns, see references/naming-and-clarity.md.

Fluent Usage and Protocols

Call sites read as grammatical English. Prefer names that form grammatical phrases at the point of use.

swift

// GOOD — reads fluently
x.insert(y, at: z)          // "x, insert y at z"
x.subviews.remove(at: i)    // "x's subviews, remove at i"
x.makeIterator()             // "x, make iterator"

// BAD — ungrammatical
x.insert(y, position: z)
x.subviews.remove(i)

Initializer first argument. The first argument to an initializer should not form a phrase continuing the type name.

swift

// GOOD
let foreground = Color(red: 32, green: 64, blue: 128)

// BAD — "Color with red" reads awkwardly
let foreground = Color(havingRGBValuesRed: 32, green: 64, blue: 128)

Protocol naming conventions:

Protocol describes	Naming pattern	Examples
What something is	Noun	`Collection` , `IteratorProtocol`
A capability	`-able` , `-ible` , or `-ing` suffix	`Equatable` , `Hashable` , `Sendable`

General Conventions

Casing. Types and protocols use

UpperCamelCase

. Everything else uses

lowerCamelCase

. Acronyms that are commonly all-caps in American English appear uniformly upper- or lower-cased based on position.

swift

var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var userSMTPServer: SMTPServer

Methods and properties over free functions. Prefer methods and properties. Use free functions only when:

There is no obvious
```
self
```
—
```
min(x, y)
```
The function is an unconstrained generic —
```
print(value)
```
The function syntax is established domain notation —
```
sin(x)
```

Default arguments over method families. Prefer a single method with default parameters over a family of methods that differ only in which parameters they accept. Place defaulted parameters at the end. Parameters with default values should always have argument labels — defaulted parameters are usually omitted at call sites, so their labels must be clear when they do appear.

swift

// GOOD — labeled with defaults
func decode(_ data: Data, encoding: String.Encoding = .utf8) -> String?

// BAD — method family
func decode(_ data: Data) -> String?
func decode(_ data: Data, encoding: String.Encoding) -> String?

Overload safety. Methods may share a base name when they operate in different type domains or when their meaning is clear from context. Avoid return-type-only overloads that cause ambiguity at the call site.

For casing edge cases, overload patterns, and tuple/closure naming, see references/conventions-and-special-rules.md.

Common Mistakes

Omitting needed argument labels. Using
```
remove(position)
```
instead of
```
remove(at: position)
```
when the role of the argument is ambiguous without the label.
Using -ed when -ing is correct. Applying
```
stripped()
```
when the past participle is ungrammatical — use
```
stripping()
```
instead. Test: does "a [verb]-ed [noun]" read naturally?
Using verb names for side-effect-free operations. Naming a nonmutating method
```
sort()
```
that returns a new collection — use
```
sorted()
```
to signal no mutation.
Naming by type instead of role. Using
```
string
```
instead of
```
greeting
```
, or
```
array
```
instead of
```
elements
```
, when the role would be more informative.
Missing documentation comments. Leaving public declarations undocumented, or writing summaries that describe the implementation rather than the purpose.
Not documenting non-O(1) computed properties. Exposing a linear-time computed property without a
```
Complexity:
```
note, causing callers to assume O(1) and use it in loops.
Applying form- prefix to verb-based operations. Writing
```
formSort()
```
instead of just
```
sort()
```
— the
```
form
```
prefix is only for noun-based operations (
```
formUnion
```
).
Factory methods without make- prefix. Naming factory methods as
```
createIterator()
```
or
```
buildBuffer()
```
instead of
```
makeIterator()
```
and
```
makeBuffer()
```
.
Repeating type information in names. Writing
```
removeElement(cancelButton)
```
or
```
stringValue: String
```
when the type is already evident from context.
Return-type-only overloads. Defining overloads that differ only in return type, creating ambiguity when the compiler cannot infer the expected type.
Unlabeled tuple members and closure parameters. Exposing tuples or closures in public API without naming their components, forcing callers to use positional access.

Review Checklist

Argument Labels

First argument follows the correct label rule (grammatical phrase, prepositional, conversion, or labeled)
Prepositional labels do not incorrectly group independent arguments
Value-preserving conversion initializers omit the first label
All non-special-case arguments have labels

Naming Semantics

Mutating methods use imperative verb form
Nonmutating methods use -ed/-ing or noun form
Mutating/nonmutating pairs follow the correct pattern (verb pair or noun/form-noun pair)
Boolean properties read as assertions (
```
isEmpty
```
,
```
isValid
```
,
```
contains
```
)
Variables and parameters are named by role, not type

Documentation

Every public declaration has a doc comment
Summaries are single sentence fragments ending in a period
Summaries describe the correct thing per declaration kind (action, access, creation, entity)
Non-O(1) computed properties document their complexity
Parameters, return values, and thrown errors are documented with symbol markup

Conventions

Types and protocols use UpperCamelCase; everything else uses lowerCamelCase
Acronyms are uniformly cased based on position
Default arguments are preferred over method families
Overloads do not differ only in return type
Protocol names follow the noun (is-a) or suffix (capability) convention

References

Naming clarity, role-based naming, weak-type compensation, and terminology: references/naming-and-clarity.md
Argument label edge cases, parameter naming, and default argument strategy: references/argument-labels-and-parameters.md
Side-effect naming examples, -ed/-ing decision tree, form- prefix patterns, and factory methods: references/side-effects-and-mutating-pairs.md
Casing edge cases, complexity documentation, overload safety, tuple/closure naming, and free function exceptions: references/conventions-and-special-rules.md

swift-api-design-guidelines

NPX Install

Tags

SKILL.md Content

Swift API Design Guidelines

Contents

Argument Label Rules

When to omit the first argument label

When to use a prepositional label

Default: label everything else

Argument label decision table

Side-Effect Naming

Functions with side effects — imperative verbs

Functions without side effects — nouns or adjective phrases

Boolean properties and methods

Mutating and Nonmutating Pairs

Verb-described operations — -ed/-ing suffix

Noun-described operations — form- prefix

Factory methods — make- prefix

Pair decision table

Documentation Comments

Summary rules by declaration kind

Symbol markup

O(1) complexity rule

Clarity and Naming

Fluent Usage and Protocols

General Conventions

Common Mistakes

Review Checklist

Argument Labels

Naming Semantics

Documentation

Conventions

References