MENU

Swift API Design Guidelines

April 23, 2018 • Read: 385 • iOS

swift

Apple Swift Style Guide Swift Style Guide

Naming

Promote Clear Usage

  • Include all the words needed to avoid ambiguity for a person reading code where the name is used.
  • Omit needless words. Every word in a name should convey salient information at the use site.
  • Name variables, parameters, and associated types according to their roles, rather than their type constraints.
  • Compensate for weak type information to clarify a parameter’s role.

Strive for Fluent Usage

  • Prefer method and function names that make use sites form grammatical English phrases.
  • Begin names of factory methods with “make”, e.g. x.makeIterator().
  • Name functions and methods according to their side-effects
  • Uses of Boolean methods and properties should read as assertions about the receiver when the use is nonmutating, e.g. x.isEmpty, line1.intersects(line2).
  • Protocols that describe a capability should be named using the suffixes able, ible, or ing (e.g. Equatable, ProgressReporting).
  • The names of other types, properties, variables, and constants should read as nouns.

Use Terminology Well

  • Avoid obscure terms if a more common word conveys meaning just as well.
  • Stick to the established meaning if you do use a term of art.
  • Avoid abbreviations. Abbreviations, especially non-standard ones, are effectively terms-of-art, because understanding depends on correctly translating them into their non-abbreviated forms.
  • Embrace precedent. Don’t optimize terms for the total beginner at the expense of conformance to existing culture.

Conventions

General Conventions

  • Document the complexity of any computed property that is not O(1).
  • Prefer methods and properties to free functions.
  • Follow case conventions. Names of types and protocols are UpperCamelCase. Everything else is lowerCamelCase.
  • Methods can share a base name when they share the same basic meaning or when they operate in distinct domains.

Parameters

  • Choose parameter names to serve documentation.
  • Take advantage of defaulted parameters when it simplifies common uses. Any parameter with a single commonly-used value is a candidate for a default.
  • Prefer to locate parameters with defaults toward the end of the parameter list.

Argument Labels

  • Omit all labels when arguments can’t be usefully distinguished, e.g. min(number1, number2), zip(sequence1, sequence2).
  • In initializers that perform value preserving type conversions, omit the first argument label, e.g. Int64(someUInt32)
  • When the first argument forms part of a prepositional phrase, give it an argument label. The argument label should normally begin at the preposition, e.g. x.removeBoxes(havingLength: 12).
  • Otherwise, if the first argument forms part of a grammatical phrase, omit its label, appending any preceding words to the base name, e.g. x.addSubview(y)
  • Label all other arguments.

Special Instructions

  • Label tuple members and name closure parameters where they appear in your API.
  • Take extra care with unconstrained polymorphism (e.g. Any, AnyObject, and unconstrained generic parameters) to avoid ambiguities in overload sets.

Last Modified: September 20, 2019
Archives Tip
QR Code for this page
Tipping QR Code