SuperAPI AI Directory

swift-api-design-guidelines

Coding & development

View repository

Updated 10-16 07:11

About this skill

Swift API Design Guidelines

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-docc skill 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) over removeElement(_ 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), not func 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"), not x.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), not x.empty or x.getIntersects(line2).
  • Mutating/nonmutating pairs follow the verb/-ed-or--ing pattern, or the form- 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 else lowerCamelCase. 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 satisfy predicate"; 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