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/conventions-and-special-rules.md

View on GitHub
# Conventions and Special Rules

Casing conventions, complexity documentation, free function exceptions, overload safety, and tuple/closure naming.

## Contents

- [Casing Conventions](#casing-conventions)
- [Complexity Documentation](#complexity-documentation)
- [Free Function Exceptions](#free-function-exceptions)
- [Overload Safety](#overload-safety)
- [Tuple Member and Closure Parameter Naming](#tuple-member-and-closure-parameter-naming)
- [Unconstrained Polymorphism](#unconstrained-polymorphism)

## Casing Conventions

Types and protocols use `UpperCamelCase`. Everything else — functions, methods, properties, variables, constants, enum cases, argument labels — uses `lowerCamelCase`.

### Acronym handling

Acronyms that appear as all-uppercase in common American English usage are uniformly upper- or lower-cased based on their position in the name.

```swift
// At the start of a lowerCamelCase name — all lowercase
var utf8Bytes: [UTF8.CodeUnit]
var htmlParser: HTMLParser
var urlSession: URLSession

// In the middle or end — follows the case of its position
var isRepresentableAsASCII = true
var userSMTPServer: SMTPServer

// Type names — acronym stays uppercase
struct HTTPRequest { ... }
class URLSessionTask { ... }
enum UTF8 { ... }
```

Words that started as acronyms but are now common words follow standard casing:

```swift
// These are words, not acronyms
var radarDetector: RadarDetector   // not "RADARDetector"
var laserPrinter: LaserPrinter     // not "LASERPrinter"
var scubaGear: ScubaGear           // not "SCUBAGear"
```

## Complexity Documentation

Callers assume computed properties are O(1). Document the complexity of any computed property or subscript that does more work.

```swift
/// The total number of nodes in the tree.
///
/// - Complexity: O(*n*), where *n* is the number of nodes.
var nodeCount: Int {
    root.descendants.count
}
```

```swift
/// The element at the given offset from the start.
///
/// - Complexity: O(*k*), where *k* is the offset.
subscript(offset: Int) -> Element {
    var current = startIndex
    for _ in 0..<offset { current = index(after: current) }
    return self[current]
}
```

Properties that are genuinely O(1) do not need a complexity note — the default assumption is correct.

```swift
// O(1) — no note needed
var count: Int { storage.count }
var isEmpty: Bool { count == 0 }
var first: Element? { storage.first }
```

## Free Function Exceptions

Prefer methods and properties to free functions. Use a free function only when one of these three conditions holds:

**1. No obvious `self`**

```swift
// GOOD — neither argument is more "self" than the other
min(x, y)
max(a, b)
zip(sequence1, sequence2)
```

**2. Unconstrained generic**

```swift
// GOOD — works on anything
print(value)
debugPrint(value)
```

**3. Established domain notation**

```swift
// GOOD — mathematical convention
sin(x)
cos(x)
abs(value)
```

If none of these apply, make it a method.

```swift
// BAD — has an obvious self
calculateDistance(from: pointA, to: pointB)

// GOOD
pointA.distance(to: pointB)
```

## Overload Safety

Methods may share a base name when they operate in different type domains or when their meaning is clear from context.

```swift
// GOOD — different parameter types, same semantic operation
extension Collection {
    func contains(_ element: Element) -> Bool
    func contains(where predicate: (Element) -> Bool) -> Bool
}
```

### Avoid return-type-only overloads

Overloads that differ only in return type create ambiguity when the compiler cannot infer the expected type.

```swift
// BAD — ambiguous at call site
func transform() -> Int { ... }
func transform() -> String { ... }

let result = transform()  // error: ambiguous
```

### Safe overloading patterns

```swift
// GOOD — different first argument labels disambiguate
func fetch(id: Int) -> User
func fetch(name: String) -> User

// GOOD — different argument types
func draw(_ rect: CGRect)
func draw(_ path: CGPath)
```

## Tuple Member and Closure Parameter Naming

Label tuple members and closure parameters in public API signatures. Positional access (`.0`, `.1`) is fragile and unreadable.

### Tuple members

```swift
// GOOD — labeled
func position() -> (x: Double, y: Double)
func range() -> (lower: Int, upper: Int)

let pos = item.position()
pos.x   // clear
pos.y   // clear

// BAD — unlabeled
func position() -> (Double, Double)

let pos = item.position()
pos.0   // what is this?
pos.1   // what is this?
```

### Closure parameters

Name closure parameters where they appear in the API, especially for higher-order functions.

```swift
// GOOD
func filter(_ isIncluded: (Element) -> Bool) -> [Element]
func map<T>(_ transform: (Element) -> T) -> [T]
func sort(by areInIncreasingOrder: (Element, Element) -> Bool)

// BAD
func filter(_ predicate: (Element) -> Bool) -> [Element]  // acceptable but less descriptive
func sort(by compare: (Element, Element) -> Bool)          // "compare" is vague
```

## Unconstrained Polymorphism

Be careful with overloads involving `Any`, `AnyObject`, or unconstrained generics. They can silently match when a more specific overload was intended.

```swift
// DANGEROUS — both overloads match array literals
struct Container {
    func append(_ element: Element)
    func append(_ sequence: some Sequence<Element>)
}

values.append([2, 3, 4])  // which overload? ambiguous if Element is Array
```

Resolve with distinct argument labels:

```swift
// GOOD — unambiguous
struct Container {
    func append(_ element: Element)
    func append(contentsOf sequence: some Sequence<Element>)
}

values.append(singleValue)
values.append(contentsOf: [2, 3, 4])  // always clear
```
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