Understanding Kotlin's Shift to Name-Based Destructuring

Kotlin is evolving its destructuring feature to be name-based rather than position-based. This change improves code clarity and refactoring safety. Below are answers to common questions about this transition.

What is name-based destructuring and why is Kotlin moving to it?

Name-based destructuring allows you to extract properties from an object by their names rather than their positions. For example, val (name, age) = person will automatically match the variables name and age to the corresponding properties of the person object, regardless of the order in which those properties were declared. Kotlin is moving to this approach to eliminate common bugs caused by accidental property swaps and to make refactoring easier. Under the current positional system, swapping two variables of the same type would go unnoticed until runtime, and changing a property’s order or adding computed properties could break destructuring silently. Name-based destructuring ties variable names directly to property names, making the code more self-documenting and robust.

Understanding Kotlin's Shift to Name-Based Destructuring — Source: blog.jetbrains.com

How does the new syntax work for name-based destructuring?

The new syntax places the variable names inside parentheses preceded by the val keyword, like val (name, age) = person. This is the same syntax as before, but the behavior changes: the variable names must match property names in the class. Kotlin also introduces an alternative syntax using square brackets for positional destructuring, such as val [a, b] = list, to preserve the old position-based behavior when needed. The name-based syntax is currently experimental and can be enabled with the compiler argument -Xname-based-destructuring=only-syntax. In the future, the parentheses syntax will become name-based by default, while square brackets will remain for positional uses.

What is the current positional destructuring and its drawbacks?

In current Kotlin, destructuring is position-based. For a data class like data class Person(val name: String, val age: Int), the declaration val (x, y) = person assigns the first component (name) to x and the second (age) to y — regardless of the variable names you choose. This means you could write val (foo, bar) = person and the code would still compile, even though foo actually holds the name property. This lack of connection between variable names and property names is error-prone. It makes refactoring difficult because changing the order of data class properties or making a property computed breaks existing destructuring silently. Additionally, it reduces code readability because the variable names don’t indicate which property they correspond to.

How can I start using name-based destructuring today?

You can start experimenting with name-based destructuring by adding the compiler argument -Xname-based-destructuring=only-syntax to your Kotlin project. This enables the new syntax rules while keeping the old behavior intact for existing code. For a more thorough preview, you can use -Xname-based-destructuring=complete to enable both the new syntax and the name-matching behavior — meaning val (name, age) = person will now enforce that the variable names correspond to actual property names. Note that both flags are experimental and subject to change. The expectation is that after a migration period, the parentheses syntax will become name-based by default, so trying it out early is encouraged.

What migration tools does the Kotlin compiler provide?

The Kotlin compiler includes helpful migration tools that warn about naming mismatches. When you enable -Xname-based-destructuring=name-mismatch, the compiler will emit warnings for any destructuring declaration where the variable names do not match the component names of the class. This lets you see potential issues before the behavior changes. Additionally, the compiler can suggest renames to align variable names with property names. For existing projects, you can run these checks and fix warnings gradually. The migration helpers are planned to be enabled by default for several releases, giving developers ample time to adapt their codebases.

Will there be a migration period and how long?

Yes, Kotlin is planning a long migration period before the default behavior of the parentheses syntax changes from positional to name-based. The exact timeline is not fixed, but the migration helpers (such as the name-mismatch warnings) will be enabled by default for several versions. During this period, you can choose to opt into the new behavior early using experimental flags, or you can wait until it becomes stable. The tools and warnings are designed to make the transition smooth. Once the new behavior becomes the default, the old positional syntax will still be available via the square bracket syntax, so no code needs to break entirely.

What happens to existing code that uses positional destructuring?

Existing code that uses the parentheses syntax for positional destructuring will continue to work during the migration period. When the default changes to name-based, any code where variable names do not match property names will produce a compile error. However, you can easily fix such code either by renaming variables to match the properties, or by switching to the new square bracket syntax (val [a, b] = person) if you intend to enforce positional behavior. The migration tools will highlight mismatches, and the compiler will suggest fixes. Because the square bracket syntax is introduced simultaneously, you have a clear migration path without losing any functionality.

Are there any experimental flags I should know about?

Yes, there are three main experimental flags: -Xname-based-destructuring=only-syntax enables the new parentheses and square bracket syntax but does not change the behavior of existing destructuring. -Xname-based-destructuring=complete enables both the new syntax and the name-matching behavior, making destructuring fully name-based. -Xname-based-destructuring=name-mismatch enables only the migration warnings, which alert you when variable names don’t match property names. All flags are currently experimental and require the -X prefix. They are available in Kotlin 2.1+ (and potentially earlier previews). Use them to experiment and prepare your code for the upcoming default change.

Tags: