Skip to content

dpearson2699/swift-ios-skills / skills/swift-api-design-guidelines

swift-api-design-guidelines

Verified

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.

references/argument-labels-and-parameters.md

View on GitHub
# Argument Labels and Parameters

Extended examples for argument label rules, edge cases, parameter naming, and default argument strategy.

## Contents

- [Prepositional Phrase Rule Edge Cases](#prepositional-phrase-rule-edge-cases)
- [Grammatical Phrase Rule Extended Examples](#grammatical-phrase-rule-extended-examples)
- [Value-Preserving vs Narrowing Conversions](#value-preserving-vs-narrowing-conversions)
- [Indistinguishable Peer Arguments](#indistinguishable-peer-arguments)
- [Parameter Naming for Documentation](#parameter-naming-for-documentation)
- [Default Arguments Over Method Families](#default-arguments-over-method-families)

## Prepositional Phrase Rule Edge Cases

The base rule: when the first argument completes a prepositional phrase with the base name, use the preposition as the argument label.

```swift
// Standard cases — preposition is the label
x.removeBoxes(havingLength: 12)
view.fade(from: red)
path.relativePath(from: root)
```

### Abstraction boundary exception

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 — forces x and y into a single prepositional phrase
a.move(toX: b, y: c)
```

```swift
// GOOD — row and column are parts of a single abstraction (a cell position)
table.cellAt(row: r, column: c)

// BAD
table.cell(atRow: r, column: c)
```

### Multiple prepositional phrases

When a method involves multiple prepositions, each argument gets its own prepositional label.

```swift
// GOOD
database.move(item, from: source, to: destination)

// GOOD
view.transition(from: oldState, to: newState, duration: 0.3)
```

## Grammatical Phrase Rule Extended Examples

When the first argument and base name form a grammatical phrase, omit the first label and absorb any leading words into the base name.

```swift
// GOOD — "add subview"
view.addSubview(child)

// GOOD — "contains element"
array.contains(element)
```

### Absorbing leading words

If the label would start with words that belong in the base name, move them.

```swift
// GOOD — "having length" absorbed into base name
removeBoxes(havingLength: 12)

// BAD — should be part of the base name
remove(boxesHavingLength: 12)
```

## Value-Preserving vs Narrowing Conversions

**Value-preserving (widening)** — the conversion cannot lose information. Omit the first label.

```swift
Int64(someUInt32)           // UInt32 always fits in Int64
String(someCharacter)       // Character is always a valid String
Double(someFloat)           // Float always fits in Double
```

**Narrowing or lossy** — the conversion may lose information or change representation. Use a descriptive label.

```swift
Int64(truncating: someDecimal)      // may lose precision
UInt32(clamping: someLargeInt)      // may clamp to bounds
String(describing: someObject)      // uses debug representation
Int(exactly: someDouble)            // may return nil
```

**Representation change** — the conversion changes how the value is viewed. Use a label that describes the interpretation.

```swift
String(utf8String: cString)         // interprets as UTF-8
Data(contentsOf: url)               // reads from file
URL(string: urlString)              // parses string as URL
```

## Indistinguishable Peer Arguments

Omit all labels when arguments are peers that cannot be usefully distinguished:

```swift
let smaller = min(x, y)
zip(sequence1, sequence2)
```

Keep labels when the values have distinct semantic roles, even if their types
match.

## Parameter Naming for Documentation

Parameter names drive the clarity of generated documentation, even though they do not appear at most call sites. Choose names that read well in a doc comment.

```swift
/// Finds the index of the equivalent element.
///
/// - Parameter element: The element to search for.
/// - Returns: The index of `element`, or `nil` if not found.
func index(of element: Element) -> Int?
```

Compare with a poorly named parameter:

```swift
/// Finds the index of the equivalent element.
///
/// - Parameter e: ???
func index(of e: Element) -> Int?
```

Name parameters as complete English words. Single letters and abbreviations damage documentation quality.

## Default Arguments Over Method Families

Prefer a single method with default parameter values over a family of methods.

```swift
// GOOD — one method, sensible defaults
func decode(
    _ data: Data,
    encoding: String.Encoding = .utf8,
    allowLossyConversion: Bool = false
) -> String?
```

```swift
// BAD — method family that differs only in which parameters are present
func decode(_ data: Data) -> String?
func decode(_ data: Data, encoding: String.Encoding) -> String?
func decode(_ data: Data, encoding: String.Encoding, allowLossyConversion: Bool) -> String?
```

### Ordering defaulted parameters

Place parameters with defaults at the end. Parameters without defaults typically carry more meaning and form the grammatical base of the call site.

```swift
// GOOD — required parameters first
func search(
    query: String,
    in scope: SearchScope = .all,
    limit: Int = 50,
    offset: Int = 0
) -> [Result]
```

Exception: when a trailing closure is the most common override, it may come after defaulted parameters.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall