Named arguments and readable call sites

Default arguments solve "I do not want to pass this every time". Named arguments solve a different problem: a call site where you cannot tell what the arguments mean. Together they make Kotlin function calls unusually readable, and this short lesson is about using them well.

The problem: unlabelled arguments

Here is a function call you will meet in every codebase:

createUser("Kavita", "kavita@example.com", true, false, 3)

What are true, false, and 3? You cannot tell without opening the function definition. This is the "boolean trap" and the "mystery number" problem — a row of unlabelled values that the reader has to decode. It is a real source of bugs, because it is easy to pass the arguments in the wrong order and the compiler cannot catch it when the types happen to line up.

Named arguments make the call self-documenting

Kotlin lets you name arguments at the call site:

createUser(
    name = "Kavita",
    email = "kavita@example.com",
    isAdmin = true,
    isVerified = false,
    maxSessions = 3
)

Now the call reads like a description of what it does. isAdmin = true says exactly what true meant. For any function with more than two or three parameters — especially booleans and numbers — naming the arguments at the call site is worth the few extra characters, because code is read far more often than it is written, and the reader is usually not you.

Named arguments let you reorder

When you name arguments, order stops mattering:

createUser(
    email = "kavita@example.com",
    name = "Kavita",              // order swapped — fine, because they are named
    maxSessions = 3,
    isAdmin = true,
    isVerified = false
)

The compiler matches by name, not position. You rarely need to reorder, but it means you never have to remember the exact parameter order — you just name what you are passing.

Named arguments plus defaults — the real power

This is where the two features combine into something genuinely useful. With defaults, you often want to supply just one of several optional parameters — and named arguments are the only clean way to do it:

fun sendMessage(
    to: String,
    body: String,
    urgent: Boolean = false,
    retries: Int = 3,
    silent: Boolean = false
) { /* ... */ }

// I want to set only `silent`, and keep the other defaults:
sendMessage("Kavita", "Your order shipped", silent = true)

Without named arguments, to set silent you would have to pass urgent and retries too, just to reach silent's position — supplying values you did not want to change. With silent = true, you skip straight to the one you care about and every other default holds. Named arguments are what make defaults practical when there are several optional parameters.

The boolean parameter, fixed

Recall the "boolean trap" — save(entry, true) tells the reader nothing. Named arguments are the cheap fix:

save(entry, notify = true)         // now the call is clear

Even better is sometimes to avoid the boolean entirely (two named functions, saveAndNotify / saveQuietly), which the best-practices module discusses. But when a boolean parameter is justified, always name it at the call site. A bare true or false in a call is a readability bug you can fix in one edit.

When you can and cannot mix

You can mix positional and named arguments, but once you start naming, everything after the first named argument must also be named (in older Kotlin) — modern Kotlin is more lenient, but the clear rule is: pass the first few obvious positional arguments if you like, then name the rest.

sendMessage("Kavita", "Order shipped", urgent = true)   // fine: positional, then named

The first two (to, body) are obvious from context and order; the optional urgent is named for clarity. That is a natural, readable style.

A guideline worth adopting

• One or two obvious parameters: positional is fine — greet("Kavita") needs no label.
• A boolean or a number whose meaning is not obvious: name it — setEnabled(enabled = true).
• More than three parameters: name most of them.
• Constructing an object with many fields (which you will do constantly with data classes): name them all — it reads like filling in a form, and it is impossible to get the order wrong.

Named arguments cost a few keystrokes and save every future reader — including you — the trip to the function definition to decode a call. That is a good trade, and it is one of the small habits that separates code that merely works from code that a team is glad to maintain.

Check your work

The problem named arguments solve. Unlabelled arguments at a call site — the boolean trap and mystery numbers — that the reader has to decode.

What naming an argument looks like. name = value at the call site.

Whether order matters with named arguments. No — the compiler matches by name.

Why named arguments make defaults practical. They let you set just one optional parameter without supplying the ones before it.

The cheap fix for a boolean parameter. Name it at the call site — notify = true.

A natural mixed style. Pass the first obvious parameters positionally, then name the rest.

When to name most arguments. More than three parameters, or constructing an object with many fields.

Practice

1. Write createUser(name, email, isAdmin, isVerified, maxSessions) and call it once positionally and once with all arguments named. Compare readability.
2. Call the named version with the arguments in a different order and confirm it still works.
3. Write sendMessage with three defaulted parameters and call it setting only the last one, using its name.
4. Take a call with a bare true and rewrite it naming the boolean.
5. Write a function with five parameters and call it in the "positional then named" mixed style.
6. Find a function call in code you have written (or a library example) with an unlabelled boolean or number, and rewrite it with named arguments.

Official documentation

• Kotlin — Functions: named arguments — The feature and its rules.
• Kotlin — Coding conventions — Guidance on when to use them.

Next: single-expression functions, for when a function is just one expression.