swift-api-design-guidelines

Swift API Design Guidelines

Naming and interface-design rules from Apple's official API Design Guidelines. The prime directive: clarity at the point of use is the goal, and clarity is more important than brevity. A declaration is written once and read at every call site — optimize the call site.

• Enforcement: most of this is judgment a linter can't check; swiftlint catches the mechanical subset (identifier casing, redundant names). See the swiftlint skill.
• Language idioms (optionals, generics, protocol design mechanics): swift-patterns.
• KMP boundary: the Swift signatures a shared Kotlin module exposes are named by Kotlin/SKIE, not by you — audit them against these rules and rename with @ObjCName / SKIE where the generated names read poorly. See kmp-ios-integration.

Contents

• Fundamentals: clarity, needed words, needless words
• Argument labels
• Defaulted parameters over method families
• Side-effect naming (pure vs mutating)
• Mutating / nonmutating pairs
• Boolean assertions
• Protocol naming
• Factories, conversions, and make
• Doc-comment structure
• Casing, acronyms, terminology
• Fintech naming examples
• Checklist
• Depth: references/naming-cookbook.md

Fundamentals: clarity, needed words, needless words

Name by role, not by type; write the whole call site out loud and make it a grammatical English phrase.

• Include all the words needed to avoid ambiguity. A word that removes ambiguity at the call site earns its place.

  employees.remove(at: x)   // clear: removes the element AT index x
  employees.remove(x)       // ambiguous: remove index x, or an element equal to x?
  

• Omit needless words. Drop words that merely repeat type information already carried by a parameter.

  allViews.remove(cancelButton)          // yes
  allViews.removeElement(cancelButton)   // "Element" adds nothing — cancelButton is obviously the element
  

• Name variables, parameters, and associated types by role, not type.

  func restock(from supplier: WidgetFactory)     // role
  func restock(from widgetFactory: WidgetFactory) // type as name — weaker
  var greeting = "Hello"      // not `var string = "Hello"`
  protocol ViewController { associatedtype ContentView : View }  // role, not `associatedtype ViewType`
  

• Compensate for weak type information. When a parameter type is Any, NSObject, a closure, or a loosely-typed collection, add a noun describing the role.

  func add(_ observer: NSObject, for keyPath: String)   // reads well
  grid.add(self, for: graphics)                          // ...but consider `addObserver(_:forKeyPath:)`