Named-only parameters

[merfemor]

This is a discussion of the "Named-only parameters" feature. The text of the proposal can be found here.

We introduce a new modifier named on function value parameters that obliges callers of this function to specify the name of this parameter.
This enhances code readability and reduces errors caused by value associated with the wrong parameter when passed in positional form.

Here's an example:

fun String.reformat(named normalizeCase: Boolean, named upperCaseFirstLetter: Boolean): String { /* body */ }

str.reformat(false, true) // ❌ ERR
str.reformat(normalizeCase = false, upperCaseFirstLetter = true) // ✅ OK

[y9san9]

Hello! It quite nice that you considered Swift in the KEEP, but you didn't elaborate on why you decided to go with named instead of giving the ability to require a specific name for the parameter:

That does have a lot of cases, so we can write functions like this:

fun String.write(to file: File) {
    // to is inaccessible
    // file is accessible
}

fun main() {
    "test".write(to = File("..."))
}

Maybe not the best example, but I hope it gives the idea

Combining with the previous idea

We also could introduce a new type of modifier that will not require to duplicate a variable name when we just want it named:

fun String.reformat(
    named normalizeCase: Boolean,
    named(uppercase) uppercaseFirstLetter: Boolean,
)

[zarechenskiy]

Oh yes, inner/outer parameters were considered. In the end, we settled on a model where the "outer" parameter (to in your example) is the one that should be declared in the function signature, as it's part of the public API. The "inner" parameter is then redeclared in the body:

fun String.write(to: File) {
    val file = to
}

This approach is natural and combines well when we need to check or preprocess the parameter (val file = check(to)).

However, it's true that it's still possible to access the original parameter, and this is something we were thinking to adjust in the future. Probably, combine it with contracts block that already has a special meaning in the "first" line of a function.

[SPC-code]

The KEEP has a quite thorough technical part, but the motivation does not seem to be robust. There is not information about how this feature interferes with other existing and planned features.

I don't see a lot of added value in this proposal. But it complicates the language. So without understanding how this feature will work with other similar features, I do not like it. In my opinion, any new lanaugage feature should solve more than one problem, unless it is a very important problem.

[OliverO2]

It seems that we're coming from different contexts: Yours is probably more about mathematics, mine is probably more about data structures, right?

I'd like to define my types in a way that makes it easy for our brains to understand, with the best fit to the problem at hand. I'd rather not change them to work around a problem with same-type positional parameters.

[nikitabobko]

(my comment is about the initial message in this thread)

@SPC-code I think it would be helpful if you could elaborate a bit more; Currently, your comment risks sounding like "I don't like this feature" without giving concrete reasons.

The KEEP has a quite thorough technical part, but the motivation does not seem to be robust

Could you clarify what you mean by "not robust"? From which perspective do you see the motivation as lacking?

Personally, I find that the motivation begins with a strong Boolean parameters example that sparks "I was there" moment. I also really like and agree with the multiple lambdas example which is an indicator of a missing feature.

There is not information about how this feature interferes with other existing and planned features.

I believe this is not quite accurate. The proposal specifically mentions interactions with overload resolution, method overrides, expect/actual matching, and data class copy.

Regarding interactions with future features, I'm not sure it's reasonable to expect an exhaustive analysis as the feature is relatively small, well-defined, and has a clear mental model and semantics (essentially just a compiler checker, much like a linter). At present, it already has very few interactions with other features, and I don't see evidence that it would introduce major complications or block future evolution of Kotlin.

[SPC-code]

Let me clarify. I do not object to specific feature design. The problem is that this feature has a very narrow use-case, but brings a lot of compexity to the language. In my opinion, if we consider only this feature, the benifit does not justify the added complexity.

If we consider larger picture. If soft keyword modifiers hava a general concept behind them, then the added complexity is not that large. And maybe it is reasonable. But then we need to see this larger picture. What is the plan for modifiers, will it be possible to extend them in plugins, how will they interact with each other. I think I have some idea about it and it it is correct, than this KEEP makes a sense. But without it, it does not.

[OliverO2]

Why do named parameters have a very narrow use case?

What does "a lot of complexity" mean?

Why do we have to consider a "larger picture" in a grand plan at this stage, instead of proceeding incrementally, gaining experience going forward?

Without concrete examples, I'm afraid that we're starting to get lost in the abstract.

[CLOVIS-AI]

Why do we have to consider a "larger picture" in a grand plan at this stage, instead of proceeding incrementally, gaining experience going forward?

Once a feature is added to the language, it can never be taken back. If we add all the small features we think of without caring about the big picture, we'll end up with a large incoherent mess.

[elizarov]

Note on positional data classes: When migrating copy function for data classes, keep in mind that some data classes are positional by design. For example, Pair and Triple from the standard library as positional, but positional data classes also exist in 3rd party libraries. Positional data classes are an exception, no a rule, but they still exist and their existence should not be ignored. It would be a mistake to turn copy function for positional data classes into a named-parameters function. You should add some mechanism (annotation or keyword) to mark positional data classes as such before proceeding to the changes in the copy function.

[y9san9]

@elizarov It can be probably achieved by copying named keywords from constructor.

An example with positional args:

data class Pair<T1, T2>(val first: T2, val second: T2) {
    // generated
   fun copy(first: T1 = this.first, second: T2 = this.second) { ... }
}

An example with named args:

data class Box<T>(named val value: T) {
    // generated
   fun copy(named value: T = this.value) { ... }
}

[zarechenskiy]

Yes! We'll mark positional data classes with a special annotation in the scope of https://github.com/Kotlin/KEEP/blob/main/proposals/KEEP-0438-name-based-destructuring.md, so that IDE and the compiler don't emit warnings on different names. And so if a class is positional, then copy function doesn't get "named" parameters

[nikitabobko]

I'd say that we want to make copy function parameters named by default not because the majority of data classes are "named" (non-positional), but because all copy function's parameters have a default value.

copy function is used to selectively swap some properties, not to recreate the whole instance from the beginning. It's inconsistent that if we selectively want to replace pair's second element, then we have to use named argument syntax; but for the first element, we don't have to use named argument syntax.

[merfemor]

+1 to Nikita
The intention of this proposal was actually not to make an exception for positional classes.
Otherwise we imply that someone needs to call copy like pair.copy(1) instead of pair.copy(first=1). But I don't see why that would be necessary.

[OliverO2]

👏 I find the proposed solution and its motivation convincing, though I had previously been exposed for quite some time to Python's * fence.

The only thing I'm not sure about: Whether Swift's default naming approach would have been preferable. But you're possibly right at hinting that this ship might have sailed.

[IRus]

Seems that this feature can be covered by annotation that would be applied to entire constructor/function and individual parameters. Plus compiler warning, that can be as well configured to report with any level: ERROR, WARN.

Also, this might be start of a bigger story, integration more lint rules directly into compiler, or via plugins.

[OliverO2]

Annotations, beginning with an @ sign and a capital letter, draw too much @Attention to what should be a benign type hint.

Please don't support cluttering the code with annotations. I've got a high logaf on that.

[IRus]

@OliverO2 I think cluttering code with named:

fun getSites(
   named partnerIds: String? = null,
   named partnerTypeIds: String? = null,
   named propertyIds: Set<Long>? = null,
   named feAppId: String? = null,
): List<SiteApiResponse> {}

not better than with a single annotation:

@Named
fun getSites(
   partnerIds: String? = null,
   partnerTypeIds: String? = null,
   propertyIds: Set<Long>? = null,
   feAppId: String? = null,
): List<SiteApiResponse> {}

And I believe that we need to think if we can add some automatic rules that would work for most cases without named at all:

• if it's copy function – require names
• more than one default parameter – require names
• more than two parameters of the same type – require names

It's will be good enough for most cases, without boilerplate and author can still add @Named

[SPC-code]

@OliverO2 how frequent should the use of this feature be? I belive that it would be quite infrequent, so drawing attention is quite alright. As for annotations, there is kindo of bad rep for annotations in Java/Kotlin ecosystem because they are frequently used for code magix. But in this case there is not code magic. It looks and walks like a code style hint. Annotations are quite allright for code style hints.

[OliverO2]

@IRus Comparing a bunch of named with a single annotation is not fair. This one better demonstrates the distracting potential of annotations:

fun getSites(
   @Named partnerIds: String? = null,
   @Named partnerTypeIds: String? = null,
   @Named propertyIds: Set<Long>? = null,
   @Named feAppId: String? = null,
): List<SiteApiResponse> {}

@SPC-code Frequency depends on the domain. Some may use it rarely, some (business, connectivity) very frequently (which may have influenced named parameters being the default in Swift). And yes, I try to focus on the use case at hand, which is not at all related to the infamous magic otherwise associated with annotations.

[IRus]

Comparing a bunch of named with a single annotation is not fair. This one better demonstrates the distracting potential of annotations:

I would say it's just a matter of taste. I think both named and @Named equally bad for declaration readability. It's not something useful to understand what function do, instead it's some linter rule backed into language (or annotation).

So first of all, I prefer not see it at all, and than if it's annotation or soft-keyword doesn't matter. One pro of annotation approach - it can be just one for the whole declaration:

@Named
public inline fun <R, T> Result<T>.fold(
    onSuccess: (value: T) -> R,
    onFailure: (exception: Throwable) -> R
) {...}

// Maybe?
public inline named fun <R, T> Result<T>.fold(
    onSuccess: (value: T) -> R,
    onFailure: (exception: Throwable) -> R
) {...}

@Named
data class UserContext(...)

// Maybe?
data class UserContext named constructor(...)

It's all looking not right

[zhelenskiy]

It seems that another missing use-case for the feature is keeping source compatibility when renaming, reordering, and adding parameters. It is useful for the end users, as they don't need to worry about the binary compatibility.

[zarechenskiy]

It's not the goal of the KEEP. We've decided to drop the compatibility aspect: it’s really hard to achieve as we can't do anything meaningful for calls from Java or for invoke calls via references. At the same time, having a solution that preserves compatibility only sometimes doesn’t seem that valuable.

[CLOVIS-AI]

Personally I don't see much need for this feature, but since it's trivial to explain to new users ("it's a parameter that must be named on the callsite") and doesn't seem to have tricky edge cases, I guess it's fine to add.

Plus, it eliminates the current hack

fun foo(
	normal: Foo,
	_n: NamedOnly = NamedOnlyImpl,
	thisParameterIsNamedOnly: Bar
) {

}

sealed class NamedOnly
private object NamedOnlyImpl : NamedOnly()

which is welcome (although thankfully few people use it, but it's mentioned every once in a while in the forums).

---

However, I'm a bit worried that library authors will overuse this and make code more complex than it needs to be. For example, the proposal mentions examples of functions where named arguments should be used, including assertEquals(expected, actual).

In my own codebases, I very often see code like

assertEquals(4, users.counter.get())
assertEquals("Daniel", users.toList().last())

The proposal is implying that this code would be more readable as:

assertEquals(expected = 4, users.counter.get())
assertEquals(expected = "Daniel", users.toList().last())

And that

listOf("a", "b", "c")
    .joinToString(", ")

would definitely be more readable as:

listOf("a", "b", "c")
    .joinToString(separator = ", ")

I disagree with both of these takes. I think this is applying this feature too far, and the current implementation is perfectly reasonable.

Now, should IntelliJ offer a quick-fix to explicitly add the named arguments for these examples? Maybe. But I don't think that code should be forbidden to write.

[CLOVIS-AI]

Still, the question is a bit different. Look at the examples in the KEEP, do you think all of them are necessary and improve the code, or do you think some are not necessary?

Alternative question: if consistency is the goal, why not make all parameters named, always? I think we all agree this would make code harder to read because many would be unnecessary, and unnecessary information makes code harder to read. To me this means there is a middle point with just enough but not too many named arguments, and I'm not convinced library authors have absolute knowledge of where that limit should be.

[CLOVIS-AI]

However, I am convinced by the use case of library authors forbidding a specific lambda parameter to be used in trailing form. I have seen multiple times cases where this would be useful. Another example could be Compose for HTML:

Div(attrs = {
    // CSS
}) {
    // Body of the div

    Input(…) {
        // Not the body! it's the attrs= parameter, because there is no body for Input!
    }
}

In this case, I do think the library author has the knowledge to make the decision, to keep consistency that the trailing lambda is only used for the body of components, and not for their configuration.

[IRus]

Alternative question: if consistency is the goal, why not make all parameters named, always? I think we all agree this would make code harder to read because many would be unnecessary, and unnecessary information makes code harder to read.

Aside from a few well-known classes/function, generally it's actually a good thing to pass parameter names:

• no requirement to remember parameters for all functions and classes in codebase
• no issues when adding new parameters
• no issues to re-order parameters
• consistent, no need to think is in this case parameters names would be welcome or not

In team we're using consistent approach to defining/calling things, with doesn't looks good for single argument, but scale well for two and more:

// declare
fun foo(
   bar: String,
): Int {
...
}

// use
foo(
    bar = "bar",
)

// consistent with constructors, which is basically just functions which always return instance of concrete type
data class User(
    val id: String,
)

val user = User(
    id = "1",
)

In this style there is no difference if you pass or not parameters in terms of "boilerplate":

// not passing parameters, no difference in lines of code, just not enough information on call side without IDEA hints.
foo(
    "bar",
)

val user = User(
    "1",
)

Which is looks basically the same with hints in IDEA:

And IDEA doing excellent job helping generating all parameter names automatically:

[fvasco]

Aside from a few well-known classes/function, generally it's actually a good thing to pass parameter names:

* no requirement to remember parameters for all functions and classes in codebase

Are you saying that it's easier to call a function by passing parameters by name rather than by position because remembering the parameter names is easier than remembering the parameters' positions?

I honestly don't understand. If I don't have to remember the parameters (for all functions and classes), how can I write log(n=8, base=2)?

(How many readers know how invoke log but haven't noticed the error?)

* no issues when adding new parameters

* no issues to re-order parameters

It seems to me that this is only valid in a limited number of cases for source compatibility, and never for binary compatibility.

* consistent, no need to think is in this case parameters names would be welcome or not

It will be consistent in all cases where the compiler knows the parameter names at compile time, but it would not be consistent in all cases where they have been removed (minification) or not included (libraries written in other languages).
It seems eventually consistent to me.

[IRus]

Are you saying that it's easier to call a function by passing parameters by name rather than by position because remembering the parameter names is easier than remembering the parameters' positions?

I honestly don't understand. If I don't have to remember the parameters (for all functions and classes), how can I write log(n=8, base=2)?

No, I'm saying that it's easier for reading. For authoring there is no difference in terms of time spent writing code, since IDEA doing great job generating list of parameters automatically.

or not included

Yea, this is definitely a pain point today, imagine calling java class constructor and not be able to pass names.

[CLOVIS-AI]

In the section "Multiple lambda arguments", please clarify what this sentence means:

In addition to that, we'd like to restrict the last lambda argument to be passed in trailing form, e.g. result.process(onSuccess = {}) { println("or error") }.

How does named force the last argument to be passed in trailing form?

[IRus]

It forcing the last argument to not be passed in trailing form:

fun process(onSuccess: () -> Unit, named onError: () -> Unit)

result.process(onSuccess = {}) { println("or error") } // compilation error

[CLOVIS-AI]

Oh that makes sense, I read the sentence the other way;

we'd like to restrict the last lambda argument to be passed in trailing form, e.g. result.process(onSuccess = {}) { println("or error") }.

we'd like to force the last lambda argument to be passed in trailing form, e.g. result.process(onSuccess = {}) { println("or error") }.

we'd like to forbid the last lambda argument to be passed in trailing form, e.g. result.process(onSuccess = {}) { println("or error") }.

I see now that that the proposal meant the last variant. I didn't realize "restrict" could mean both opposites here, it's inconvenient.

[eygraber]

I'm with @CLOVIS-AI here. I read that the same way.

[zarechenskiy]

Yep, it's meant the way @IRus described it. @merfemor, let's clarify this part?

[merfemor]

Thanks, fixed!

[IRus]

I know that there is no KEEP for dataarg, but given design shared at KotlinConf 2024:

How named might interact with dataarg parameters? I believe it make sense to make all of them named by-default, so we will have implicit named-only parameters as well?

[BenWoodworth]

I was wondering if the dataargs idea was still being considered. I know there's this proposal that seems like it's trying to solve the same issue: #431

[fvasco]

I'm afraid this kind of feature opens the door to a new wave of requests: Please add named to field xyz.

Is it really necessary to define in the function interface how parameters should be passed?
named would have made more sense if it allowed parameters to be passed by name (similar to how infix allows infix calls), but adding it just to forbid certain positional parameters doesn’t seem like an unquestionable improvement to me.

[zarechenskiy]

I'm afraid this kind of feature opens the door to a new wave of requests: Please add named to field xyz.

If such a request makes sense, why do you think it could be harmful?

Is it really necessary to define in the function interface how parameters should be passed?

So far, we’ve seen several use cases for this feature:

• Functions like log, where the first parameter is positional and the second (base) is named
  • Functions like withParent(parent, withSelf), parent — positional, withSelf — named
• Functions with a named first parameter followed by a trailing lambda like map(to = ...) { ... } as discussed here
• Functions with a positional first parameter followed by a trailing lambda (withTimeout(1000) { ... })
• Functions with a positional first parameter, then a bunch of named parameters and followed by a trailing lambda (like withTimeOut function)
• Functions like minOf, where the first two parameters are positional and the third (comparator) is named
  • In general, functions that take vararg positionally, and then a lambda in a trailing form
• UI functions like Text(text: String, modifier: Modifier, color: Color, ...), where the first parameter is positional and the rest are named
• All named parameters

It's true that "all named" functions could be considered as a special (maybe main?) case, and we might consider extending the design for that. Feedback from @IRus also highlights a similar idea: when a function has three or more parameters, it might be preferable to require all of them to be named, so could have named functions and a linter inspection to use named if there are too many parameters.

For now, the design is intentionally flexible. We want to see how it works out in practice before optimizing for specific scenarios.

[fvasco]

@zarechenskiy

If such a request makes sense, why do you think it could be harmful?

The debate about whether or not to add named to xyz, I wouldn't be surprised if it was very similar to what's already taking place in this thread.

So far, we’ve seen several use cases for this feature:

There are many use cases where passing arguments by name is a wonderful idea, but it seems to me that the discussion is about forcing developers to write code a certain way and that this decision should be part of a function's interface.
We need use cases where not forcing developers to pass some arguments by name is definitely a bad idea. In this case, named solves this problem.

The examples provided are helpful, but they seem somewhat arbitrary and open to question.
In some cases, requiring parameter names compensates for a lack of typing (boolean fits all). In others, the choice feels inconsistent (e.g., src vs. dst), or it disregards well-established conventions (such as top, right, bottom, left).

The solution for Checked Exceptions was "Avoid Checked Exception," and I fear that named will suffer the same fate.

[CLOVIS-AI]

If such a request makes sense, why do you think it could be harmful?

Each such request (if accepted) will mean a depreciation cycle + breaking source-compatibility at some point in the future. That seems to be a very high cost.

[fvasco]

Feedback from @IRus also highlights a similar idea: when a function has three or more parameters, it might be preferable to require all of them to be named

Triple(first = a, second = b, third = c)

Really?
Can I vote No?

---

so could have named functions and a linter inspection to use named if there are too many parameters.

A method with 10 (ten) positional parameters, it is OK for me.
A linter for this feature is out of scope for a KEEP. I fully support creating a custom linter with a configurable 'too many"' threshold.

[zarechenskiy]

I don’t think there’s any intention to make such calls named. It’s clear that named parameters wouldn’t help in these cases when you create a position-based object. I'd avoid stretching the idea that far

[IRus]

Triple(first = a, second = b, third = c)

Really? Can I vote No?

I would say this is example of code that shouldn't be written in the first place.

Same example but with some code from production:

// no idea if object created correctly when reviewing in Gitlab or there for example
DefaultUserContext(
   user.email,
   user.id,
   user.permissions.toSet(),
)

// clear mapping between params, similar to builder in java
DefaultUserContext(
   id = user.id,
   email = user.email,
   permissions = user.permissions.toSet(),
)

[IRus]

And would rather make sacrifice for a few positional-based cases (maybe instead of marking named parameters, we could mark positional parameters, since they are rare. Or allow to do both), then create inconsistency language-wise.

When in project you'll have to write something like this:

// library using named
str.reformat(normalizeCase = false, upperCaseFirstLetter = true)

// library not marking parameters as named, so in diverse team likely both named and unnamed usage
str.sanitize(false, true)

That's why I strongly believe that to be consistent, this should be a rule enabled by default in compiler (allow opt-out) rather then optional soft-keyword or annotation

[OliverO2]

This particular discussion shows that context matters. There is no one-size-fits-all approach if one context is vectors (positional parameters fit, even in large numbers) and the other one is personal or business data (named parameters fit, even if only few).

[fvasco]

@zarechenskiy @IRus @OliverO2
I agree with all of you.
We should define a global rule and a way to skip this constraint, it's not a promising start for me.

// no idea if object created correctly when reviewing in Gitlab or there for example
DefaultUserContext(
   user.email,
   user.id,
   user.permissions.toSet(),
)

Use a proper types, compilers does the rest.

class DefaultUserContext(email: UserEmail, id: UserId, permissions: Set<UserPermission>)