In Swift, what is the difference between a parameter's argument label and its parameter name, and what does writing _ change at the call site?
answer
- two names per parameter
- one for callers, one for the body
- label defaults to the name
- underscore removes the label
- labels are part of the function's name
basics
~20 sA Swift argument label is the word callers write before an argument; the parameter name is what the function body uses. The label defaults to the name, a separate word overrides it, and _ removes it.
solid answer
~40 sEvery Swift parameter has an **argument label** (used at the call site) and a **parameter name** (used inside the body). Writing one identifier, `retries: Int`, makes it both. Writing two, `to recipient: User`, gives callers `to:` and the body `recipient`. Writing `_ message: Message` suppresses the label, so the argument is passed bare. Labels are part of the function's full name, `send(_:to:retries:)`, so the compiler enforces them: a missing label, an extra label or a wrong label is an error, and arguments must keep their declared order. The point is a call site that reads like a phrase: `send(message, to: alice, retries: 2)`.
code
swift · 10 linesstruct Message { let text: String }
struct User { let id: String }
func send(_ message: Message, to recipient: User, retries: Int = 3) {
print("send '\(message.text)' to \(recipient.id), retries \(retries)")
}
let alice = User(id: "alice")
send(Message(text: "hi"), to: alice)
send(Message(text: "hi"), to: alice, retries: 0)go deeper
Recall the three forms: one identifier for both roles, label then name, and _ to drop the label. Be ready to write send(_:to:retries:) and call it.
Explain that labels belong to the function's full name, which is why the compiler rejects missing, extra or reordered labels and why labels can distinguish overloads.
Talk about designing an SDK surface: write the call site first, pick labels that form a phrase, and use _ only where the base name already names the argument.
Frame labels as a public contract: renaming one is a source-breaking change for every caller, so an SDK's labels deserve the same review as its types.
## Two names for one parameter In Swift every function parameter carries two identifiers: - **Argument label** — the word the *caller* writes in front of the argument. - **Parameter name** — the local constant the *function body* reads. When you write a single identifier, it plays both roles. When you write two, the first is the label and the second is the name. When the first is an underscore, the label is suppressed and the caller passes the argument with no label at all. ```swift func send(_ message: Message, to recipient: User, retries: Int = 3) { // the body reads message, recipient and retries } send(hello, to: alice) // reads as a phrase send(hello, to: alice, retries: 0) ``` Here the first parameter has no label (`_`), the second has the label `to` and the name `recipient`, and the third uses `retries` for both. | Declaration | Call site | Name in the body | |---|---|---| | `retries: Int` | `retries: 2` | `retries` | | `to recipient: User` | `to: alice` | `recipient` | | `_ message: Message` | `hello` (no label) | `message` | ## Why Swift has both The two names serve different readers. The caller reads the call site, and Swift wants that line to read like a sentence: `send(hello, to: alice)` says what happens without anyone opening the declaration. The implementer reads the body, where `recipient` is a clearer noun than the preposition `to`. Apple's API Design Guidelines build on this split: a label is chosen for how the call reads, and a first argument whose role is already obvious from the base name usually drops its label with `_`. The book's own wording: argument labels let a function be called "in an expressive, sentence-like manner, while still providing a function body that's readable and clear in intent." ## Labels are part of the function's name Swift identifies a function by its base name plus its labels. The function above is `send(_:to:retries:)`, and that full name is what the compiler resolves. Three consequences follow: 1. **The compiler enforces labels exactly.** Leaving one out, adding one or spelling one differently is a compile error, not a warning. 2. **Order is fixed.** Even though labels name each argument, you cannot reorder them; the compiler reports that one argument must precede another. 3. **Labels distinguish overloads.** `fetch(id:)` and `fetch(name:)` are two different functions that can share a base name, and the call site picks one by its label. Two things the label is *not*: - It is not a keyword-argument map you can shuffle, as in some dynamic languages. - It is not part of a stored function value's type: assign `fetch(id:)` to a constant and you call that constant without labels. That behaviour belongs with function types as values. ## What the compiler says The diagnostics are worth recognising, because they name the exact fix: - `extraneous argument label 'text:' in call` — the declaration used `_`, but the caller wrote a label. - `missing argument label 'to:' in call` — the caller omitted a required label. - `argument 'to' must precede argument 'retries'` — the caller reordered labelled arguments. Parameter names, by contrast, are invisible to callers. Two declarations that differ only in parameter names — `f(a x: Int)` and `f(a y: Int)` — have the same full name `f(a:)`, so the second is an `invalid redeclaration`. ## Rules worth knowing - Parameter names must be unique within a function; argument labels may repeat, though unique labels read better. - A bare `_` with no name after it, written as `_: Int`, makes a parameter the body cannot read at all. - Methods follow the same rules as free functions: since Swift 3 the first parameter of a method is labelled by default, just like the others. - Initializers use labels the same way, which is why `Array(repeating:count:)` reads as it does. ## A practical reading test When designing an SDK call, write the call site first and read it aloud. `send(message, to: user, retries: 3)` passes. `send(message: message, recipient: user, numberOfRetries: 3)` repeats what the types already say. `send(message, user, 3)` hides which argument is which. The label is the tool that moves a call from the second or third form to the first, and `_` is the tool for the argument whose role the base name already states.
- Can two Swift functions share a base name if they differ only in their argument labels?Yes. Labels are part of the full name, so `fetch(id: Int)` and `fetch(name: String)` are distinct functions and the call site selects one by its label. Differing only in *parameter names* is not enough: `f(a x: Int)` and `f(a y: Int)` are both `f(a:)`, and the compiler reports an invalid redeclaration.
- When should a Swift API drop the first argument label with _?When the base name already says what the first argument is, so a label would only repeat it: `send(message, to: user)`, `array.append(element)`. Keep a label when the argument's role would otherwise be unclear or when it forms a phrase with the base name, as `to:` does. Read the call site aloud; the guideline is about how it reads, not about saving keystrokes.
- Argument labels are optional at the call site, like comments
- Labelled arguments can be passed in any order
- The parameter name is what callers write before the argument
- Two overloads can differ only in their parameter names
- Writing _ before a parameter name hides that parameter from the body