Functions, argument labels and parameters

A call such as fare(3, 11, true) hides its meaning: is 3 where the journey starts or how many people travel, and what does true switch on? With Swift’s argument labels the same call reads fare(fromKm: 3, toKm: 11, class: .first), and in this lesson’s made-up fare table it costs 40 rupees, twice the standard fare of 20.

You will declare functions whose calls read like that, let callers leave out arguments that have defaults, take any number of fares with a variadic parameter, return a tuple or nothing at all, change a caller’s variable with inout, see why one variable cannot fill two inout parameters, and name functions the way the Swift API Design Guidelines advise.

A parameter has a label for the call and a name for the body

In labels.swift the fare function is declared as fare(fromKm start: Int, toKm end: Int, class travelClass: TravelClass). Each parameter has two names. The first is the argument labelargument label: The name a call writes before an argument, as fromKm in fare(fromKm: 3, toKm: 11). It may differ from the parameter name the function's body uses, and an underscore in its place means the call writes no label., which the caller writes: fromKm: 3. The second is the parameter name, which only the body uses: start. The Swift Programming Language gives every function parameter both. Step through the call and watch each value take its parameter’s name:

Three patterns cover nearly every declaration. Two names, as in fromKm start, give the caller a phrase and the body a short name. One name, as in farePerKm(fare: Int, km: Int), serves as both, because a parameter’s name is its label unless you write another. An underscore, as in isPeakHour(_ hour: Int), removes the label, so the call is isPeakHour(9): the function’s name already says what 9 is. A keyword other than inout, var and let may be a label without backticks, which is how class: can label a parameter whose name in the body is travelClass.

// labels.swift: an argument label for the call, a parameter name for the body.
enum TravelClass {
    case standard, first
}

// The fare table of this lesson, made up for it: rupees by distance.
func fare(fromKm start: Int, toKm end: Int, class travelClass: TravelClass) -> Int {
    let base = switch abs(end - start) {
    case 0...3: 10
    case 4...8: 20
    case 9...15: 30
    case 16...25: 40
    default: 50
    }
    return travelClass == .first ? base * 2 : base
}

// One name: it is the argument label and the parameter name.
func farePerKm(fare: Int, km: Int) -> Double {
    Double(fare) / Double(km)
}

// An underscore: the call has no label, because the function's name says enough.
func isPeakHour(_ hour: Int) -> Bool {
    (8...10).contains(hour) || (17...20).contains(hour)
}

print("standard, km 3 to 11:", fare(fromKm: 3, toKm: 11, class: .standard))
print("first, km 3 to 11:", fare(fromKm: 3, toKm: 11, class: .first))
print("per km:", farePerKm(fare: 20, km: 8))
print("peak at 9:", isPeakHour(9), "peak at 14:", isPeakHour(14))

standard, km 3 to 11: 20
first, km 3 to 11: 40
per km: 2.5
peak at 9: true peak at 14: false

A call writes the labels exactly as declared, in the declaration’s order. Here is what the compiler says to one call that uses the parameter names instead, and to one that leaves the labels out:

// wrong_labels.swift: calls that use the parameter names, or no labels, where labels belong.
func fare(fromKm start: Int, toKm end: Int) -> Int {
    abs(end - start) <= 3 ? 10 : 20
}

print(fare(start: 3, end: 11))
print(fare(3, 11))

from session import run, version

# wrong_labels.swift calls fare(fromKm:toKm:) once with its parameter names and once with no labels at all.
version()
run("""
!swiftc wrong_labels.swift -o wrong_labels
""")

# Apple Swift version 6.4 (swiftlang-6.4.0.34.1)
$ swiftc wrong_labels.swift -o wrong_labels
wrong_labels.swift:6:11: error: incorrect argument labels in call (have 'start:end:', expected 'fromKm:toKm:')
4 | }
5 | 
6 | print(fare(start: 3, end: 11))
  |           `- error: incorrect argument labels in call (have 'start:end:', expected 'fromKm:toKm:')
7 | print(fare(3, 11))
8 | 

wrong_labels.swift:7:11: error: missing argument labels 'fromKm:toKm:' in call
5 | 
6 | print(fare(start: 3, end: 11))
7 | print(fare(3, 11))
  |           `- error: missing argument labels 'fromKm:toKm:' in call
8 | 
[exit status 1]

Each diagnosticdiagnostic: A message from the compiler about the code: an error, which stops the build, a warning, which does not, or a note that adds detail. Each starts with the file, the line and the column. More in “Compiler errors, language modes and feature flags” names the labels the call should have written, fromKm:toKm:. The labels belong to the call and the names to the body, and neither can stand in for the other.

Default values and variadic parameters let one function take many calls

Most journeys are standard class, so asking every caller to say so is noise. A default valuedefault value: A value written after a parameter's type, as in class travelClass: TravelClass = .standard. A call may leave that argument out, and the function then uses the default., written after the parameter’s type, lets a call leave that argument out: with class travelClass: TravelClass = .standard, the call fare(fromKm: 3, toKm: 11) is a standard fare. A variadic parametervariadic parameter: A parameter written with three dots after its type, as in fares: Int..., that takes zero or more separate values. The function receives them as an array, here [Int]; an array cannot be passed in their place. goes the other way and takes any number of values, written with three dots after its type: fares: Int.... This program uses both, and prints what the variadic parameter holds inside the function:

// defaults_variadic.swift: a default value, a variadic parameter, and two variadic parameters.
enum TravelClass {
    case standard, first
}

func fare(fromKm start: Int, toKm end: Int, class travelClass: TravelClass = .standard) -> Int {
    let base = switch abs(end - start) {
    case 0...3: 10
    case 4...8: 20
    case 9...15: 30
    case 16...25: 40
    default: 50
    }
    return travelClass == .first ? base * 2 : base
}

func total(of fares: Int...) -> Int {
    print("  inside total(of:), fares is \(type(of: fares)):", fares)
    var sum = 0
    for fare in fares {
        sum += fare
    }
    return sum
}

func balance(start: Int, fares: Int..., topUps: Int...) -> Int {
    var left = start
    for fare in fares {
        left -= fare
    }
    for topUp in topUps {
        left += topUp
    }
    return left
}

print("class left out:", fare(fromKm: 3, toKm: 11))
print("class given:", fare(fromKm: 3, toKm: 11, class: .first))
print("three fares:", total(of: 20, 30, 20))
print("no fares:", total())
print("balance:", balance(start: 50, fares: 20, 30, topUps: 100))

class left out: 20
class given: 40
  inside total(of:), fares is Array<Int>: [20, 30, 20]
three fares: 70
  inside total(of:), fares is Array<Int>: []
no fares: 0
balance: 100

Inside total(of:), fares is an Array<Int>. The three fares arrived as [20, 30, 20], and a call with no fares at all, total(), gave the function an empty array and returned 0. This table lists what each call handed over:

Since Swift 5.4 a function may have several variadic parameters (SE-0284), as balance(start:fares:topUps:) does. One rule keeps such calls readable: the parameter after a variadic one must have a label, so topUps: marks where the fares end. Put parameters with defaults at the end of the list, as The Swift Programming Language advises. The API Design Guidelines add that an argument with a default should always keep its label: a call may leave it out, so it never takes part in the phrase that the rest of the call reads as.

// array_to_variadic.swift: an array passed where separate values are expected.
func total(of fares: Int...) -> Int {
    var sum = 0
    for fare in fares {
        sum += fare
    }
    return sum
}

let fares = [20, 30, 20]
print(total(of: fares))

from session import run, version

# array_to_variadic.swift passes an array to total(of:), whose parameter is variadic.
version()
run("""
!swiftc array_to_variadic.swift -o array_to_variadic
""")

# Apple Swift version 6.4 (swiftlang-6.4.0.34.1)
$ swiftc array_to_variadic.swift -o array_to_variadic
array_to_variadic.swift:11:17: error: cannot pass array of type '[Int]' as variadic arguments of type 'Int'
 9 | 
10 | let fares = [20, 30, 20]
11 | print(total(of: fares))
   |                 `- error: cannot pass array of type '[Int]' as variadic arguments of type 'Int'
12 | 
[exit status 1]

A function returns one value, a tuple or nothing

distance(fromKm:toKm:) has one line in its body, abs(end - start), and no return. When the whole body of a function is a single expression, the function returns that expression: closures always had this shorthand, and functions gained it in Swift 5.1 (SE-0255). farePerKm(fare:km:) and isPeakHour(_:) in labels.swift are written the same way. This program returns four kinds of result:

// returns.swift: one value, a tuple, an optional tuple, and nothing at all.
func distance(fromKm start: Int, toKm end: Int) -> Int {
    abs(end - start)
}

func split(_ total: Int, among people: Int) -> (each: Int, left: Int) {
    (total / people, total % people)
}

func cheapestAndDearest(_ fares: [Int]) -> (cheapest: Int, dearest: Int)? {
    guard var cheapest = fares.first else {
        return nil
    }
    var dearest = cheapest
    for fare in fares {
        cheapest = min(cheapest, fare)
        dearest = max(dearest, fare)
    }
    return (cheapest, dearest)
}

func printTicket(fromKm start: Int, toKm end: Int) {
    print("ticket: km \(start) to km \(end)")
}

print("distance:", distance(fromKm: 3, toKm: 11))
let share = split(100, among: 3)
print("each pays", share.each, "and", share.left, "is left over")
if let range = cheapestAndDearest([30, 10, 50, 20]) {
    print("cheapest:", range.cheapest, "dearest:", range.dearest)
}
if cheapestAndDearest([]) == nil {
    print("no fares, no range: nil")
}
let nothing: Void = printTicket(fromKm: 3, toKm: 11)
print("printTicket returned:", nothing)

distance: 8
each pays 33 and 1 is left over
cheapest: 10 dearest: 50
no fares, no range: nil
ticket: km 3 to km 11
printTicket returned: ()

A tupletuple: A group of a few values of any types, written in brackets, such as (low: 98, high: 201). Its parts are read by label, by position (.0, .1) or by destructuring, and it needs no declaration. More in “Operators, ranges and tuples” returns a few values together without declaring a type for them, and its labels name each part where it is used: share.each and share.left. A ? after the tuple’s closing bracket makes the whole tuple optional, which says that sometimes there is no answer at all. An empty list has no cheapest fare, and nil says so, where (cheapest: 0, dearest: 0) would be a wrong answer that looks right. A function without -> returns Void, which The Swift Programming Language defines as the empty tuple, (), and that is what the program printed for nothing.

Swift warns when a call drops the value a function returns, because a dropped result is often a mistake. Mark a function @discardableResult when ignoring its result is normal, as for printReceipt(_:), whose job is to print, and whose total a caller may want or not. The standard library marks Array’s remove(at:) the same way. This session compiles and runs a program that ignores three results:

// unused.swift: results that nobody uses.
func fare(fromKm start: Int, toKm end: Int) -> Int {
    abs(end - start) <= 3 ? 10 : 20
}

@discardableResult
func printReceipt(_ fares: [Int]) -> Int {
    var sum = 0
    for fare in fares {
        sum += fare
    }
    print("receipt:", fares.count, "fares, total", sum)
    return sum
}

var stops = ["Churchgate", "Dadar", "Thane"]
stops.remove(at: 0)
fare(fromKm: 3, toKm: 11)
printReceipt([20, 30])
_ = fare(fromKm: 0, toKm: 2)
print("stops left:", stops)

from session import run, version

# unused.swift ignores three results: remove(at:) and printReceipt(_:) are marked @discardableResult, fare is not.
version()
run("""
swiftc unused.swift -o unused
./unused
""")

# Apple Swift version 6.4 (swiftlang-6.4.0.34.1)
$ swiftc unused.swift -o unused
unused.swift:18:1: warning: result of call to 'fare(fromKm:toKm:)' is unused [#NoUsage]
16 | var stops = ["Churchgate", "Dadar", "Thane"]
17 | stops.remove(at: 0)
18 | fare(fromKm: 3, toKm: 11)
   | `- warning: result of call to 'fare(fromKm:toKm:)' is unused [#NoUsage]
19 | printReceipt([20, 30])
20 | _ = fare(fromKm: 0, toKm: 2)

[#NoUsage]: <https://docs.swift.org/compiler/documentation/diagnostics/no-usage>
$ ./unused
receipt: 2 fares, total 50
stops left: ["Dadar", "Thane"]

Only the call of fare(fromKm:toKm:) drew a warning, and the program still compiled and ran. The line _ = fare(fromKm: 0, toKm: 2) drops a result on purpose, and says so to the compiler and to the next reader.

An inout parameter changes a variable of the caller

Parameters are constants: a plain fare: Int can be read in the body but not changed. Marking the parameter inout lets the function change the caller’s variable, and the call says so with &: applyDiscount(&fare, percent: 10) turned 40 into 36. The & is there so that whoever reads the call sees which variables it may change.

// inout.swift: functions that change the caller's variables.
func applyDiscount(_ fare: inout Int, percent: Int) {
    fare -= fare * percent / 100
}

func move(_ amount: Int, from source: inout Int, to target: inout Int) {
    source -= amount
    target += amount
}

var fare = 40
applyDiscount(&fare, percent: 10)
print("fare after 10 percent off:", fare)

var ashaCard = 200
var raviCard = 30
move(50, from: &ashaCard, to: &raviCard)
print("Asha's card:", ashaCard, "Ravi's card:", raviCard)

swap(&ashaCard, &raviCard)
print("after swap:", ashaCard, raviCard)

fare after 10 percent off: 36
Asha's card: 150 Ravi's card: 80
after swap: 80 150

The Swift Programming Language describes an in-out parameterin-out parameter: A parameter marked inout. The function may change it, and its value is written back to the caller's variable when the function returns. The call passes a variable with &, as in applyDiscount(&fare, percent: 10). as copy-in copy-out: the call copies the argument’s value into the parameter, the body changes the copy, and when the function returns, the copy is written back to the caller’s variable. The compiler may use the variable’s own memory instead, as an optimisation, so write code that is correct under the copy model. Step through move(50, from: &ashaCard, to: &raviCard) in that model:

Only a variable can be an inout argument: not a constant, not a literal, and never without &. The standard library’s swap(_:_:) is a function like move, with two inout parameters. One variable cannot fill both parameters of one call, though. In the copy model, move(50, from: &card, to: &card) would start both parameters at 200, end them at 150 and 250, and write both back to card, so the result would depend on which write came last. An inout parameter has exclusive accessSwift's rule that while code changes a variable, no other access to that variable may overlap in time. An inout parameter's access lasts for the whole call, so a second inout argument that is the same variable would overlap with it. to its variable for the whole call, and Swift refuses the call at compile time. This session compiles both mistakes:

// no_ampersand.swift: an inout argument without &, and a constant passed as one.
func applyDiscount(_ fare: inout Int, percent: Int) {
    fare -= fare * percent / 100
}

var fare = 40
applyDiscount(fare, percent: 10)
let dayPass = 120
applyDiscount(&dayPass, percent: 10)

// aliasing.swift: one variable passed to both inout parameters.
func move(_ amount: Int, from source: inout Int, to target: inout Int) {
    source -= amount
    target += amount
}

var card = 200
move(50, from: &card, to: &card)
print(card)

from session import run, version

# no_ampersand.swift leaves out the & and passes a constant; aliasing.swift passes one variable to both inout parameters.
version()
run("""
!swiftc no_ampersand.swift -o no_ampersand
!swiftc aliasing.swift -o aliasing
""")

# Apple Swift version 6.4 (swiftlang-6.4.0.34.1)
$ swiftc no_ampersand.swift -o no_ampersand
no_ampersand.swift:7:15: error: passing value of type 'Int' to an inout parameter requires explicit '&'
 5 | 
 6 | var fare = 40
 7 | applyDiscount(fare, percent: 10)
   |               `- error: passing value of type 'Int' to an inout parameter requires explicit '&'
 8 | let dayPass = 120
 9 | applyDiscount(&dayPass, percent: 10)

no_ampersand.swift:9:15: error: cannot pass immutable value as inout argument: 'dayPass' is a 'let' constant
 6 | var fare = 40
 7 | applyDiscount(fare, percent: 10)
 8 | let dayPass = 120
   | `- note: change 'let' to 'var' to make it mutable
 9 | applyDiscount(&dayPass, percent: 10)
   |               `- error: cannot pass immutable value as inout argument: 'dayPass' is a 'let' constant
10 | 
[exit status 1]
$ swiftc aliasing.swift -o aliasing
aliasing.swift:8:27: error: inout arguments are not allowed to alias each other
 6 | 
 7 | var card = 200
 8 | move(50, from: &card, to: &card)
   |                |          `- error: inout arguments are not allowed to alias each other
   |                `- note: previous aliasing argument
 9 | print(card)
10 | 
[exit status 1]

The compiler names each mistake in its own words: the & is required, a let constant cannot be changed, and “inout arguments are not allowed to alias each other”, where to alias means to name the same memory.

Labels and types tell overloads apart, and functions can nest

overloads.swift declares three functions called fare: one takes fromKm: and toKm:, one takes a route and one takes a list of routes. Swift tells them apart by their full names, written with the labels, such as fare(fromKm:toKm:), the form the warning in the last section printed. Where the labels match, the types of the arguments decide. Declaring functions like this is called overloadingoverloading: Declaring several functions with the same base name that differ in their argument labels or parameter types, such as fare(fromKm:toKm:) and fare(for:). Each call runs the one its labels and argument types fit., and the API Design Guidelines allow it when the functions share one basic meaning, as these do: each works out a fare. Route is a type aliastype alias: A second name for an existing type, declared with typealias, such as typealias Paise = Int. The alias and the original are the same type, so values of the two mix freely. More in “Operators, ranges and tuples” for a tuple of two distances.

// overloads.swift: one base name, three functions, told apart by their labels and types.
typealias Route = (fromKm: Int, toKm: Int)

func fare(fromKm start: Int, toKm end: Int) -> Int {
    switch abs(end - start) {
    case 0...3: 10
    case 4...8: 20
    case 9...15: 30
    case 16...25: 40
    default: 50
    }
}

func fare(for route: Route) -> Int {
    fare(fromKm: route.fromKm, toKm: route.toKm)
}

func fare(for routes: [Route]) -> Int {
    var sum = 0
    for route in routes {
        sum += fare(for: route)
    }
    return sum
}

// A nested function: add(_:) is visible only inside report(_:), and it changes report's lines.
func report(_ routes: [Route]) -> [String] {
    var lines: [String] = []
    func add(_ route: Route) {
        lines.append("km \(route.fromKm) to \(route.toKm): \(fare(for: route))")
    }
    for route in routes {
        add(route)
    }
    lines.append("day total: \(fare(for: routes))")
    return lines
}

let today: [Route] = [(fromKm: 3, toKm: 11), (fromKm: 11, toKm: 3), (fromKm: 0, toKm: 2)]
print("fare(fromKm:toKm:)", fare(fromKm: 3, toKm: 11))
print("fare(for:) with a Route", fare(for: (fromKm: 0, toKm: 2)))
print("fare(for:) with [Route]", fare(for: today))
for line in report(today) {
    print(line)
}

fare(fromKm:toKm:) 20
fare(for:) with a Route 10
fare(for:) with [Route] 50
km 3 to 11: 20
km 11 to 3: 20
km 0 to 2: 10
day total: 50

Step through how the call fare(for: today) finds its function among the three:

The labels ruled out fare(fromKm:toKm:), and the type of today, an array, ruled out the version that takes one route. The guidelines also advise against functions that differ only in the type they return, because type inference cannot always tell such calls apart.

add(_:) is declared inside report(_:): it is a nested functionnested function: A function declared inside the body of another function. Only the enclosing function can call it, and it can read and change that function's variables.. The rest of the program cannot see it, and only report(_:) can call it. It also reads and changes a variable of the function around it: each call of add appended a line to report’s lines. A function that uses the variables of the place where it was written is said to capture them, and capturing is what the next lesson’s closures build on.

Name a function so that its call reads as a phrase

The API Design Guidelines put one goal first: clarity at the point of use, where a function is called, which matters more than brevity. Every word of a name should carry information, and parameters are named for their role, not for their type. Three of its rules decide most labels in this lesson. An argument that completes a phrase that starts with a preposition gets a label: fare(fromKm:toKm:), total(of:). An argument that continues the function’s name as a phrase gets none: isPeakHour(9). Every other argument is labelled: percent:. Here are calls before and after those rules:

The last row is about effects. The guidelines name a function that changes something with an imperative verb, applyDiscount, and one that returns a new value instead with a noun or an “-ed” form, discounted, the way the standard library pairs sort() with sorted(). A reader then knows from the name alone whether fare changes.

Practise: a metro card in five functions

Write five functions for a metro card, so that each call reads as a phrase:

• fare(fromKm:toKm:class:), this lesson’s fare table, with .standard as the default class;
• total(of:), the sum of any number of fares, given one by one;
• discounted(_:percent:), a fare after a percentage off, returned as a new value;
• topUp(_:by:limit:), which adds money to a card balance in place, never past a limit of 1,000 unless the call gives another, and returns how much it added, a result that callers may ignore;
• longestTrip(in:), the route that covers the most kilometres, or nil when there are no routes.

Write and test yours before reading this version:

// practice.swift: one way to write the five functions of the metro card.
enum TravelClass {
    case standard, first
}

typealias Route = (fromKm: Int, toKm: Int)

func fare(fromKm start: Int, toKm end: Int, class travelClass: TravelClass = .standard) -> Int {
    let base = switch abs(end - start) {
    case 0...3: 10
    case 4...8: 20
    case 9...15: 30
    case 16...25: 40
    default: 50
    }
    return travelClass == .first ? base * 2 : base
}

func total(of fares: Int...) -> Int {
    var sum = 0
    for fare in fares {
        sum += fare
    }
    return sum
}

func discounted(_ fare: Int, percent: Int) -> Int {
    fare - fare * percent / 100
}

@discardableResult
func topUp(_ balance: inout Int, by amount: Int, limit: Int = 1000) -> Int {
    let added = max(0, min(amount, limit - balance))
    balance += added
    return added
}

func longestTrip(in routes: [Route]) -> Route? {
    guard var longest = routes.first else {
        return nil
    }
    for route in routes where abs(route.toKm - route.fromKm) > abs(longest.toKm - longest.fromKm) {
        longest = route
    }
    return longest
}

let morning = fare(fromKm: 3, toKm: 11)
let evening = fare(fromKm: 11, toKm: 3, class: .first)
let errand = fare(fromKm: 0, toKm: 2)
let outing = fare(fromKm: 5, toKm: 30)
print("fares:", morning, evening, errand, outing)
let sum = total(of: morning, evening, errand, outing)
print("total:", sum, "with 20 percent off:", discounted(sum, percent: 20))

var balance = 950
let added = topUp(&balance, by: 100)
print("added", added, "so the balance is", balance)
topUp(&balance, by: 100)
print("at the limit, the balance stays", balance)

let today: [Route] = [(fromKm: 3, toKm: 11), (fromKm: 0, toKm: 2), (fromKm: 5, toKm: 30)]
if let longest = longestTrip(in: today) {
    print("longest trip: km \(longest.fromKm) to \(longest.toKm)")
}
print("no trips:", longestTrip(in: []) == nil ? "nil" : "a trip")

fares: 20 40 10 40
total: 110 with 20 percent off: 88
added 50 so the balance is 1000
at the limit, the balance stays 1000
longest trip: km 5 to 30
no trips: nil

topUp(_:by:limit:) is @discardableResult, so its second call needs no _ =, and it adds only 50 of the 100 asked for, because the card stops at 1,000. longestTrip(in:) returns an optional tuple, nil for an empty list. Then work through the practice round: it starts with the idea you know least and moves up a level after each right answer.

Interview questions

Warm-up: what is the difference between an argument label and a parameter name in Swift?

The argument label is the name a caller writes before an argument, and the parameter name is the name the function’s body uses for it. In func fare(fromKm start: Int, toKm end: Int) the labels are fromKm and toKm, so the call is fare(fromKm: 3, toKm: 11), while the body reads start and end. Writing one name makes it both, and _ as the label removes it from calls. Labels are part of the function’s full name, fare(fromKm:toKm:), so they also tell overloads apart. The two names serve different readers: the label makes the call read as a phrase, and the parameter name keeps the body short and clear. A call must use the labels exactly, in order; using the parameter names instead is a compile-time error.

Key takeaways

• Each parameter has an argument label, which the call writes, and a parameter name, which the body uses; one name serves as both, and _ removes the label.
• A default value lets a call leave an argument out, and a variadic parameter takes any number of separate values, which the body receives as an array.
• A single-expression body returns its value without return; a tuple returns a few named values, an optional tuple may return none, and a function without -> returns Void.
• An inout parameter writes its changes back to the caller’s variable, the call marks it with &, and one variable cannot be passed to two inout parameters of the same call.
• Overloads share a base name and differ in their labels or parameter types, and a nested function is visible only inside the function that declares it.
• Names and labels are right when the call reads as a short, exact phrase, as the Swift API Design Guidelines advise.