dpearson2699/swift-ios-skills / skills/swift-api-design-guidelines
swift-api-design-guidelines
VerifiedApply 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.9 KB |
| evals/evals.json | config | 5.2 KB |
| references/argument-labels-and-parameters.md | markdown | 5.2 KB |
| references/conventions-and-special-rules.md | markdown | 5.6 KB |
| references/naming-and-clarity.md | markdown | 4.6 KB |
| references/side-effects-and-mutating-pairs.md | markdown | 5.5 KB |
references/side-effects-and-mutating-pairs.md
View on GitHub# Side Effects and Mutating Pairs
Extended examples for side-effect naming, the -ed/-ing decision tree, form- prefix patterns, Boolean naming, and factory methods.
## Contents
- [Side-Effect Naming Extended Examples](#side-effect-naming-extended-examples)
- [The -ed/-ing Decision Tree](#the--ed-ing-decision-tree)
- [Form- Prefix Patterns](#form--prefix-patterns)
- [Boolean Naming Patterns](#boolean-naming-patterns)
- [Factory Method Naming](#factory-method-naming)
## Side-Effect Naming Extended Examples
### Mutating — imperative verbs
Methods that change the receiver's state use imperative verb form.
```swift
array.sort()
array.append(newElement)
array.removeAll()
set.insert(member)
dictionary.updateValue(newValue, forKey: key)
buffer.replaceSubrange(range, with: newElements)
```
### Nonmutating — nouns, past participles, descriptions
Methods that return a value without changing the receiver use a form that describes the result.
```swift
let sorted = array.sorted()
let distance = point.distance(to: origin)
let trimmed = string.trimmingCharacters(in: .whitespaces)
let union = setA.union(setB)
let successor = index.advanced(by: 1)
let prefix = array.prefix(3)
```
### Mixed — same type, both variants
When both exist, the naming makes the difference obvious at every call site.
```swift
// Mutating
array.sort()
// Nonmutating — returns new value
let newArray = array.sorted()
// Mutating
set.formUnion(other)
// Nonmutating — returns new value
let combined = set.union(other)
```
## The -ed/-ing Decision Tree
Use this decision tree to choose between `-ed` and `-ing` for the nonmutating variant of a verb-described operation.
**Step 1: Try the past participle (`-ed`).** Read the phrase: "a [verb]-ed [noun]". If it sounds grammatical, use `-ed`.
```
sort → sorted ✓ "a sorted array" sounds correct
sortLines → sortedLines ✓ "sorted lines" describes the result
reverse → reversed ✓ "a reversed collection" sounds correct
shuffle → shuffled ✓ "a shuffled deck" sounds correct
```
**Step 2: Does -ed fail the result-description test?**
Use the present participle (`-ing`) 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.
```
append → appending "appended" does not describe the returned receiver clearly
stripNewlines → strippingNewlines direct-object pattern from the guidelines
```
### Extended -ed/-ing examples and naming patterns
| Mutating | Nonmutating | Suffix | Reasoning |
|----------|-------------|--------|-----------|
| `sort()` | `sorted()` | -ed | "a sorted array" |
| `sortLines()` | `sortedLines()` | -ed | "sorted lines" describes the result |
| `reverse()` | `reversed()` | -ed | "a reversed collection" |
| `shuffle()` | `shuffled()` | -ed | "a shuffled deck" |
| `append(_:)` | `appending(_:)` | -ing | `appended` does not describe the returned receiver clearly |
| `filter(_:)` | `filter(_:)` | n/a | nonmutating only in stdlib |
| `drop(while:)` | `drop(while:)` | n/a | nonmutating only in stdlib |
## Form- Prefix Patterns
The `form` prefix applies only to noun-described operations where the nonmutating version is the noun itself.
### Standard library examples
| Nonmutating (noun) | Mutating (form- prefix) |
|---------------------|------------------------|
| `union(other)` | `formUnion(other)` |
| `intersection(other)` | `formIntersection(other)` |
| `symmetricDifference(other)` | `formSymmetricDifference(other)` |
### When NOT to use form-
Do not apply `form` to verb-described operations. The imperative verb form is already the mutating version.
```swift
// WRONG — sort is a verb, not a noun
mutating func formSort() // ✗
mutating func sort() // ✓
// WRONG — append is a verb
mutating func formAppend(_:) // ✗
mutating func append(_:) // ✓
```
The `form` prefix exists because the noun form (`union`) is naturally the nonmutating name, and the mutating version needs a distinct name. Verbs do not have this problem — the imperative (`sort`) and participle (`sorted`) are already distinct.
## Boolean Naming Patterns
Boolean properties and methods read as assertions about the receiver. They answer a yes/no question.
```swift
// Properties — "is" prefix for adjectives
line.isEmpty
url.isFileURL
connection.isSecure
view.isHidden
option.isEnabled
// Properties — no prefix for verb phrases
set.contains(element) // "set contains element"
string.hasPrefix("https") // "string has prefix"
array.canAppend(element) // "array can append element"
// BAD patterns
line.empty // is this a verb ("empty the line") or adjective?
list.include // verb or boolean?
node.leaf // noun, not an assertion
```
## Factory Method Naming
Factory methods that create and return a new value use the `make` prefix. This distinguishes them from initializers and from methods that return existing values.
```swift
// GOOD — factory creates a new value
let iterator = collection.makeIterator()
let buffer = parser.makeBuffer()
let snapshot = store.makeSnapshot()
// BAD — wrong prefix
let iterator = collection.createIterator() // use "make"
let buffer = parser.buildBuffer() // use "make"
let snapshot = store.getSnapshot() // "get" implies retrieval, not creation
```
The `make` prefix signals to callers that the returned value is freshly created, distinct from any cached or shared state.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |