13. Named Arguments — Making Calls Self‑Documenting

13. Named Arguments — Making Calls Self‑Documenting

This is another place where AI often gets things subtly wrong.
Named arguments let us call functions and methods with clarity and intention.
Instead of relying on parameter order or remembering what each value means, we can name the arguments directly at the call site.

They reflect a broader shift in modern PHP:
→meaning should be visible where it matters.

1. What Named Arguments Are

Named arguments allows us to specify parameter names when calling a function:

sendEmail(
    to: $user->email,
    subject: 'Welcome',
    urgent: true,
);

The call becomes self‑documenting.
No guessing.
No relying on memory or parameter order.

2. Why Modern PHP Uses Them

Named arguments reduce:

ambiguity
reliance on parameter order
cognitive load
mistakes when functions evolve
the need to look up signatures constantly

They make calls clearer,
especially when functions have many parameters or optional ones.

3. The Mental Model

Named arguments are clarity at the call site.

They don’t change behavior.
They don’t add new capabilities.
They simply make the meaning of each value explicit.

The key idea → Use named arguments when clarity matters more than brevity.

4. A Simple Example

Without named arguments:

scheduleMeeting($date, $duration, true, false);

What do the booleans mean here?
We would have to look it up, but look at the next example.

With named arguments:

scheduleMeeting(
    date: $date,
    duration: $duration,
    notifyTeam: true,
    record: false,
);

The meaning is visible.
The call is honest.

5. When to Use Named Arguments

Use named arguments when:

a function has many parameters
boolean flags appear in the call
the meaning of values isn’t obvious
we want clarity at the call site
we want future‑proof calls (order can change)

Named arguments shine in controllers, services,
and any place where readability matters.

6. When Not to Use Named Arguments

Avoid them when:

the call is simple and obvious
the function is internal and may change names
the parameter names are unstable or private
the verbosity outweighs the clarity

Named arguments are for readability,
not verbosity.

When AI Gets This Wrong

AI often mixes named and positional arguments, or uses named arguments for internal functions where parameter names are not stable. Sometimes it invents parameter names that don’t exist, or uses named arguments where the call is already clear.

Our mental model helps us see when named arguments improve clarity
— and when AI is using them simply because they “look explicit”.

Summary

Named arguments make calls self‑documenting.
They reduce ambiguity, improve readability,
and help the code express meaning directly at the call site.

Once we internalize this,
we can immediately see when AI‑generated code:

invents parameter names
mixes named and positional arguments
uses named arguments unnecessarily
or misses opportunities to clarify meaning

Named arguments are a small feature
— but they teach us how modern PHP
wants to express intention where it matters most.

Top↑
Back to Topic ↔
Home←

Table of Contents