Reference: swift.org/documentation/api-design-guidelines.
The test for every rule below is the same: read the call site, not the declaration. A name is declared once and used many times, so an awkward declaration that reads fine at the use site beats a tidy declaration that reads badly there. When in doubt, write the call site out and read it as an English phrase.
Fundamentals
- Clarity at the point of use outranks brevity. Swift's terseness should come from the type system and inference, not from cutting words a reader needs.
- Every public declaration gets a documentation comment (see the
swift-doccskill for the format and building the catalog). If the summary is hard to write in one sentence fragment, the API is probably shaped wrong — fix the design before you fix the doc comment.
Promote Clear Usage
- Include every word needed to avoid ambiguity at the call site.
remove(at: position)vs.remove(position)— the second reads like "remove the element equal to position," which is wrong. - Omit words that don't add information, especially ones that just repeat the type:
remove(_ member: Element)overremoveElement(_ member: Element)—allViews.remove(cancelButton)already tells you what's being removed. - Name parameters, variables, and associated types after their role, not their type.
func restock(from widgetFactory: WidgetFactory), notfunc restock(from factory: WidgetFactory)repurposed as if the type name were the role.
Strive for Fluent Usage
- Prefer names that make the call site read as a grammatical English phrase:
x.insert(y, at: z)("x, insert y at z"), notx.insert(y, position: z). - It's fine for fluency to degrade after the first argument or two, once those arguments stop
being central to the call's meaning (e.g. trailing
options:/completionHandler:). - Factory methods start with
make:x.makeIterator(). - The first argument to an initializer or factory method doesn't form a phrase with the base
name — don't chase grammatical continuity there:
let foreground = Color(red: 32, green: 64, blue: 128) // good let foreground = Color(havingRGBValuesRed: 32, ...) // no — forcing a phrase - Boolean methods and properties read as assertions about the receiver:
x.isEmpty,line1.intersects(line2), notx.emptyorx.getIntersects(line2). - Mutating/nonmutating pairs follow the verb/
-ed-or--ingpattern, or theform- prefix when there's no natural participle:x.sort()/x.sorted(),x.append(y)/x.appending(y),x.formUnion(y)/x.union(y). - Protocols that describe what something is read as nouns (
Collection). Protocols that describe a capability use-able/-ible/-ing(Equatable,ProgressReporting).
Use Terminology Well
- Prefer the common word over the term of art when both convey the meaning — don't say "epidermis" for "skin."
- If you do use a term of art, use it exactly as the field already uses it. Don't invent a new meaning for an existing term; an expert reader will trust the familiar meaning and be misled.
- Avoid abbreviations, especially non-standard ones — they're terms of art too, understandable only if the reader can guess the expansion.
- Embrace precedent: reuse names and patterns the standard library and Apple frameworks already
established (
Sequence,map,flatMap) instead of inventing parallel vocabulary.
General Conventions
- Document the complexity of any computed property that isn't O(1) — callers assume property access is free.
- Prefer methods and properties to free functions. Free functions are for the cases with no
obvious
self(min(x, y)), unconstrained generics (print(x)), or established math notation (sin(x)). - Case conventions: types and protocols are
UpperCamelCase, everything elselowerCamelCase. Acronyms that are conventionally all-caps stay all-caps as a unit (utf8Bytes,userSMTPServer); other acronyms are treated as ordinary words (radarDetector).
Parameters
- Choose parameter names for how they read in the generated documentation, not just at the call
site —
filter(_ predicate: ...)documents naturally as "elements that satisfypredicate";filter(_ includedInResult: ...)doesn't. - Give a parameter a default when one value is overwhelmingly common — it simplifies the call site for the typical case without losing the explicit form for the rest.
Argument Labels
func move(from start: Point, to end: Point)
x.move(from: x, to: y)
- Omit all labels when arguments can't be usefully distinguished:
min(number1, number2),zip(sequence1, sequence2). - In an initializer that performs a value-preserving type conversion, omit the first label —
the source type is already the whole story:
String(veryLargeNumber). In a narrowing conversion, label the narrowing:UInt32(truncating: someUInt64),UInt32(saturating: someUInt64). - If the first argument forms part of a prepositional phrase, label it starting at the
preposition, with the label itself beginning right after that preposition:
a.moveTo(x: b, y: c),a.fadeFrom(red: b, green: c, blue: d). - Otherwise, if the first argument is part of a grammatical phrase, omit its label and fold any
preceding words into the base name:
x.addSubview(y). If it isn't part of a phrase, it needs a label:view.dismiss(animated: false).
Special Instructions
- Label tuple members and name closure parameters wherever they appear in your API — those names carry explanatory power and can be referenced from doc comments, even though closure-parameter labels aren't visible at the call site.
- Take extra care with unconstrained polymorphism (
Any,AnyObject, unconstrained generics) — it's easy to create ambiguous overloads that only differ under the hood.
Common mistakes
| Mistake | Fix |
|---|---|
removeElement(_:) |
remove(_:) — the type name in the method name is redundant with the call site |
remove(x) for "remove at position x" |
remove(at: x) — bare noun implies value-equality removal |
Color(havingRGBValuesRed:green:andBlue:) |
Color(red:green:blue:) — don't force initializer args into a phrase with the base name |
x.getIntersects(y) / x.empty |
x.intersects(y) / x.isEmpty — booleans read as assertions |
x.sort() returning a new array |
x.sorted() for the nonmutating form; sort() implies mutation |
A capability protocol named as an adjective-less noun, e.g. Progress for something reporting progress |
ProgressReporting — capability protocols take -able/-ible/-ing |
A free function where a method would do (describe(x)) |
Make it a method (x.describe()) unless there's no obvious self |
Abbreviated parameter name (fn, cfg) |
Full word (function, configuration) — abbreviations are terms of art |