Swift API Design Guidelines
Apply Swift API Design Guidelines to name, label, and document Swift APIs.
Install
npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines -g -a claude-code -y- Repository
- dpearson2699/swift-ios-skills1.3k
- Category
- Design
- Updated
- 3mo ago
- License
- See repository
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- No, instructions only
What it does
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.
Swift API Design Guidelines
Apply the Swift API Design Guidelines to naming, labels, documentation, and
call-site clarity. For mixed requests, handle the API-design portion here and
route language/type-system work to swift-language, concurrency to
swift-concurrency, and lint configuration to swiftlint.
Contents
- 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 the first matching row:
| 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) |
Load Argument Labels and Parameters when resolving abstraction boundaries, multiple prepositions, conversion initializers, indistinguishable peers, parameter naming, or default arguments.
Side-Effect Naming
Use imperative verbs for operations with side effects, result-describing noun or adjective phrases for operations without side effects, and assertion-style names for Boolean APIs.
