Naming

Promote Clear Usage

• Include all the words needed to avoid ambiguity for a person reading code where the name is used.

  For example, consider a method that removes the element at a given position within a collection.

    ✅
    extension List {
    public mutating func remove(at position: Index) -> Element
    }
    employees.remove(at: x)
  

  If we were to omit the word at from the method signature, it could imply to the reader that the method searches for and removes an element equal to x, rather than using x to indicate the position of the element to remove.

    ❌
    employees.remove(x) // unclear: are we removing x?
  

• Omit needless words. Every word in a name should convey salient information at the use site.

  More words may be needed to clarify intent or disambiguate meaning, but those that are redundant with information the reader already possesses should be omitted. In particular, omit words that merely repeat type information.

    ❌
    public mutating func removeElement(_ member: Element) -> Element?
  
    allViews.removeElement(cancelButton)
  

  In this case, the word Element adds nothing salient at the call site. This API would be better:

    ✅
    public mutating func remove(_ member: Element) -> Element?
  
    allViews.remove(cancelButton) // clearer
  

  Occasionally, repeating type information is necessary to avoid ambiguity, but in general it is better to use a word that describes a parameter’s role rather than its type. See the next item for details.

• Name variables, parameters, and associated types according to their roles, rather than their type constraints.

    ❌
    var string = "Hello"
    protocol ViewController {
        associatedtype ViewType : View
    }
    class ProductionLine {
        func restock(from widgetFactory: WidgetFactory)
    }
  

  Repurposing a type name in this way fails to optimize clarity and expressivity. Instead, strive to choose a name that expresses the entity’s role.

    ✅
    var greeting = "Hello"
    protocol ViewController {
        associatedtype ContentView : View
    }
    class ProductionLine {
        func restock(from supplier: WidgetFactory)
    }
  

  If an associated type is so tightly bound to its protocol constraint that the protocol name is the role, avoid collision by appending Protocol to the protocol name:

    protocol Sequence {
        associatedtype Iterator : IteratorProtocol
    }
    protocol IteratorProtocol { ... }
  

• Compensate for weak type information to clarify a parameter’s role.

  Especially when a parameter type is NSObject, Any, AnyObject, or a fundamental type such Int or String, type information and context at the point of use may not fully convey intent. In this example, the declaration may be clear, but the use site is vague.

    ❌
    func add(_ observer: NSObject, for keyPath: String)
  
    grid.add(self, for: graphics) // vague
  

  To restore clarity, precede each weakly typed parameter with a noun describing its role:

    ✅
    func addObserver(_ observer: NSObject, forKeyPath path: String)
    grid.addObserver(self, forKeyPath: graphics) // clear
  

Strive for Fluent Usage

• Prefer method and function names that make use sites form grammatical English phrases.

    ✅
    x.insert(y, at: z)          “x, insert y at z”
    x.subViews(havingColor: y)  “x's subviews having color y”
    x.capitalizingNouns()       “x, capitalizing nouns”
  

    ❌
    x.insert(y, position: z)
    x.subViews(color: y)
    x.nounCapitalize()
  

  It is acceptable for fluency to degrade after the first argument or two when those arguments are not central to the call’s meaning:

    AudioUnit.instantiate(
        with: description, 
        options: [.inProcess], completionHandler: stopProgressBar)
  

• Begin names of factory methods with “make”, e.g. x.makeIterator().

• The first argument to initializer and factory methods calls should not form a phrase starting with the base name, e.g. x.makeWidget(cogCount: 47)

  For example, the first arguments to these calls do not read as part of the same phrase as the base name:

    ✅
    let foreground = Color(red: 32, green: 64, blue: 128)
    let newPart = factory.makeWidget(gears: 42, spindles: 14)
    let ref = Link(target: destination)
  

  In the following, the API author has tried to create grammatical continuity with the first argument.

    ❌
    let foreground = Color(havingRGBValuesRed: 32, green: 64, andBlue: 128)
    let newPart = factory.makeWidget(havingGearCount: 42, andSpindleCount: 14)
    let ref = Link(to: destination)
  

  In practice, this guideline along with those for argument labels means the first argument will have a label unless the call is performing a value preserving type conversion.

    let rgbForeground = RGBColor(cmykForeground)
  

• Name functions and methods according to their side-effects

  • Those without side-effects should read as noun phrases, e.g. x.distance(to: y), i.successor().

  • Those with side-effects should read as imperative verb phrases, e.g., print(x), x.sort(), x.append(y).

  • Name Mutating/nonmutating method pairs consistently. A mutating method will often have a nonmutating variant with similar semantics, but that returns a new value rather than updating an instance in-place.

    • When the operation is naturally described by a verb, use the verb’s imperative for the mutating method and apply the “ed” or “ing” suffix to name its nonmutating counterpart.

      Mutating	Nonmutating
      x.sort()	z = x.sorted()
      x.append(y)	z = x.appending(y)

      • Prefer to name the nonmutating variant using the verb’s past participle (usually appending “ed”):

        /// Reverses `self` in-place.
        mutating func reverse()
      
        /// Returns a reversed copy of `self`.
        func reversed() -> Self
        ...
        x.reverse()
        let y = x.reversed()
      

      • When adding “ed” is not grammatical because the verb has a direct object, name the nonmutating variant using the verb’s present participle, by appending “ing.”

        /// Strips all the newlines from `self`
        mutating func stripNewlines()
      
        /// Returns a copy of `self` with all the newlines stripped.
        func strippingNewlines() -> String
        ...
        s.stripNewlines()
        let oneLine = t.strippingNewlines()
      

    • When the operation is naturally described by a noun, use the noun for the nonmutating method and apply the “form” prefix to name its mutating counterpart.

      Nonmutating	Mutating
      x = y.union(z)	y.formUnion(z)
      j = c.successor(i)	c.formSuccessor(&i)

• 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 what something is should read as nouns (e.g. Collection).

• 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

Term of Art
noun - a word or phrase that has a precise, specialized meaning within a particular field or profession.

• Avoid obscure terms if a more common word conveys meaning just as well. Don’t say “epidermis” if “skin” will serve your purpose. Terms of art are an essential communication tool, but should only be used to capture crucial meaning that would otherwise be lost.

• Stick to the established meaning if you do use a term of art.

  The only reason to use a technical term rather than a more common word is that it precisely expresses something that would otherwise be ambiguous or unclear. Therefore, an API should use the term strictly in accordance with its accepted meaning.

  • Don’t surprise an expert: anyone already familiar with the term will be surprised and probably angered if we appear to have invented a new meaning for it.

  • Don’t confuse a beginner: anyone trying to learn the term is likely to do a web search and find its traditional meaning.

• Avoid abbreviations. Abbreviations, especially non-standard ones, are effectively terms-of-art, because understanding depends on correctly translating them into their non-abbreviated forms.

  The intended meaning for any abbreviation you use should be easily found by a web search.

• Embrace precedent. Don’t optimize terms for the total beginner at the expense of conformance to existing culture.

  It is better to name a contiguous data structure Array than to use a simplified term such as List, even though a beginner might grasp the meaning of List more easily. Arrays are fundamental in modern computing, so every programmer knows—or will soon learn—what an array is. Use a term that most programmers are familiar with, and their web searches and questions will be rewarded.

  Within a particular programming domain, such as mathematics, a widely precedented term such as sin(x) is preferable to an explanatory phrase such as verticalPositionOnUnitCircleAtOriginOfEndOfRadiusWithAngle(x). Note that in this case, precedent outweighs the guideline to avoid abbreviations: although the complete word is sine, “sin(x)” has been in common use among programmers for decades, and among mathematicians for centuries.