thiennc-tesoglobal Swift API Design Guidelines
Design APIs that read clearly at the call site and communicate semantic roles rather than implementation details.
Contents
- Scope and Compatibility
- Call-Site Test
- Side Effects and Pairs
- Names and Protocols
- Documentation
- Common Mistakes
- Review Checklist
- References
Scope and Compatibility
This skill owns Swift declaration names, argument labels, mutating/nonmutating pairs, protocol naming, casing, overload clarity, and documentation comments. Route language/type-system mechanics to swift-language, concurrency semantics to swift-concurrency, lint configuration to swiftlint, and project/file naming to the relevant architecture or UI skill.
Preserve source compatibility when it is part of the request. Before renaming public API, inspect access level, protocol requirements, generated interfaces, call sites, and whether a deprecation/forwarding period is needed. Verify version-specific language behavior in primary Swift sources.
Call-Site Test
Read every proposed call as a sentence. Keep words that clarify the role of an argument; remove words that merely repeat its type or the declaration context.
Use the first applicable rule:
| Situation | Label strategy |
|---|---|
| Value-preserving conversion initializer | Omit first label |
Indistinguishable peer values such as min(x, y) |
Omit peer labels |
| First argument completes the base-name phrase | Omit or fold words into the base name |
| Argument begins a prepositional phrase | Use that preposition as the label |
| General case | Use a role-based label |
Read Argument Labels and Parameters for grammatical/prepositional edge cases, conversions, peers, defaults, and multi-argument abstractions.
Side Effects and Pairs
- Use imperative verbs for mutating operations:
sort(),append(_:). - Name nonmutating results with a noun/adjective or grammatical participle:
sorted(),appending(_:). - For noun operations, use the noun for the returned value and
formplus noun for mutation:union(_:)/formUnion(_:). - Use
makefor factories when creation is the semantic action. - Name Boolean properties and methods as assertions:
isEmpty,contains(_:).
Read Side Effects and Mutating Pairs when -ed versus -ing, form, Boolean, or factory grammar is unclear.
Names and Protocols
- Name variables and parameters by role, not type.
- Prefer terms established by the domain and use one word for one concept.
- Avoid abbreviations unless they are conventional and unambiguous.
- Name protocols describing a thing as nouns; name capability protocols with an appropriate
-able,-ible, or-ingform. - Prefer methods/properties when there is a natural
self; use free functions for symmetric peers, unconstrained generic operations, or established notation. - Avoid overloads distinguishable only by return type.
Read Naming and Clarity for role names, terminology, weak-type compensation, and fluent usage.
Documentation
Public API should have concise documentation that states purpose, parameters, return value, thrown errors, side effects, and relevant complexity. Function summaries describe what the operation does; type/property summaries describe what the declaration is.
Document non-constant complexity when callers could reasonably assume O(1). Use symbol links and parameter markup supported by DocC. Do not restate the declaration in prose.
Read Conventions and Special Rules for casing, complexity, tuples, closure labels, overloads, and documentation edge cases.
Common Mistakes
- Omitting argument labels when the argument's role is not immediately obvious from the function base name.
- Violating the mutating/non-mutating naming rule (e.g. using a noun for a mutating method instead of
form...). - Repeating type information in parameter labels (e.g.
remove(element: item)instead ofremove(item)). - Naming boolean properties or methods as commands rather than assertions (e.g.
checkEmpty()vsisEmpty). - Creating method overloads distinguishable only by return type, causing ambiguous type inference.
Review Checklist
- The call reads naturally with values substituted
- Labels describe semantic roles and do not repeat type information
- Side-effect and mutating/nonmutating names are grammatical
- Boolean APIs read as assertions
- Names use consistent domain terminology
- Protocol names communicate thing versus capability semantics
- Defaults simplify one API instead of creating redundant method families
- Overloads remain unambiguous without relying on return type
- Public documentation explains behavior, errors, side effects, and non-O(1) complexity where relevant
- Public renames include an appropriate compatibility strategy
References
- Naming clarity and terminology
- Argument labels and parameters
- Side effects and mutating pairs
- Casing, documentation, overloads, tuples, and closures