Kotlin's Shift to Name-Based Destructuring: A New Era for Property Access

Kotlin is evolving its destructuring mechanism to make names the primary way to extract properties from objects. Currently, destructuring relies on the position of properties, which can lead to subtle bugs and hinder refactoring. In the future, val (name, age) = person will extract properties by their names rather than their order. This change introduces new syntax and a careful migration plan to ensure a smooth transition. Below, we answer the most common questions about this significant update.

• What is name-based destructuring and why is it being introduced?
• How does the new syntax for name-based destructuring work?
• What is changing with positional destructuring and the new square bracket syntax?
• Why is Kotlin moving away from position-based destructuring?
• How will the migration from positional to name-based destructuring be handled?
• What compiler flags are available to experiment with the new features?
• When will the new behavior become stable?

What is name-based destructuring and why is it being introduced?

Name-based destructuring lets you extract properties from an object by their names instead of their positions. For example, val (name, age) = person will match the properties name and age regardless of the order they are declared in the class. This change is being introduced to eliminate a common source of bugs where developers accidentally swap properties because destructuring was position-based. It also enables better refactoring – for instance, you can compute a property on the fly without breaking destructuring code. The Kotlin team believes that name-based destructuring makes code more readable and robust, aligning with the language’s emphasis on clarity and safety.

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

The new syntax places val inside parentheses. So instead of val (name, age) = person (where the variables correspond by position), the new style explicitly names the properties: val (name = name, age = age) = person. More concisely, when the variable names match the property names, you can write val (name, age) = person – but the compiler will interpret this as name-based matching, not positional. This syntax is currently experimental and can be enabled with the compiler flag -Xname-based-destructuring=only-syntax. It allows you to write destructuring declarations that bind to properties by name, making the intent clear and reducing the risk of order-related errors.

What is changing with positional destructuring and the new square bracket syntax?

To complement name-based destructuring, Kotlin is introducing a dedicated syntax for positional destructuring using square brackets. For example, val [first, second] = pair would extract components by their position (0, 1). This syntax makes it explicit when you intend to use positional matching, separating it from the name-based default. Currently, val (first, second) is ambiguous, but in the future, parentheses will imply name-based, and square brackets will imply positional. This change helps avoid confusion and clarifies developer intent. The square bracket syntax is also experimental under the same compiler flag.

Why is Kotlin moving away from position-based destructuring?

Position-based destructuring, while simple, has significant drawbacks. It ties variable names to the order in which properties are declared, which is brittle. A common mistake is swapping two properties of the same type – the code compiles but behaves incorrectly. Additionally, refactoring becomes painful: if you change the order of properties or convert a property to a computed one, all positional destructuring usages may break silently. By moving to name-based matching, Kotlin makes destructuring more resilient to changes and easier to reason about. The compiler can also provide better validation and tooling support. The shift aligns with modern language design trends that favor explicit naming for clarity and safety.

How will the migration from positional to name-based destructuring be handled?

Kotlin has a careful migration plan. The current behavior (positional) remains the default for now. A long transition period allows developers to gradually adopt the new name-based syntax. Compiler flags control the behavior: -Xname-based-destructuring=name-mismatch enables migration helpers that warn when a destructuring variable name differs from the corresponding property name. Later, -Xname-based-destructuring=complete switches to the new behavior entirely. Tooling like IntelliJ IDEA will offer automatic refactorings to update existing code. The Kotlin team will keep the old behavior available for several versions before changing the default, giving ample time for migration.

What compiler flags are available to experiment with the new features?

Currently, three experimental flags are available: -Xname-based-destructuring=only-syntax enables the new syntax (parentheses for name-based, square brackets for positional) without changing the meaning of existing code. -Xname-based-destructuring=name-mismatch activates migration helpers that flag potential mismatches between variable names and property names in positional destructuring. -Xname-based-destructuring=complete fully switches to name-based destructuring by default, making parentheses name-based and requiring square brackets for positional. All flags are experimental and require -Xname-based-destructuring to be enabled. Developers are encouraged to try them out and provide feedback before the feature becomes stable.

When will the new behavior become stable?

The new name-based destructuring is currently Experimental and is expected to become Stable in a future release of Kotlin. The team has not specified a definitive version, but they have committed to a gradual rollout. The migration helpers will be enabled by default for several versions, giving developers time to adapt. The exact timeline will depend on community feedback and the resolution of any remaining design issues. In the meantime, you can start experimenting with the compiler flags mentioned above to prepare your codebase for the eventual switch.