Previewed in JDK 21

Unnamed variables and unnamed patterns first previewed in JDK 21 via JEP 443, which was titled Unnamed Patterns and Variables. We here propose to finalize this feature without change.

Purpose

Capture developer intent that a given binding or lambda parameter is unused, and enforce that property, so as to clarify programs and reduce opportunities for error.
Improve the maintainability of all code by identifying variables that must be declared (e.g., in catch clauses) but are not used.
Allow multiple patterns to appear in a single case label, provided that none of them declare any pattern variables.
Improve the readability of record patterns by eliding unnecessary nested type patterns.

Problems and issues before unnamed variable and unnamed pattern

Developers sometimes declare variables that they do not intend to use, whether as a matter of code style or because the language requires variable declarations in certain contexts. The intent of non-use is known at the time the code is written, but if it is not captured explicitly then later maintainers might accidentally use the variable, thereby violating the intent. If we could make it impossible to accidentally use such variables then code would be more informative, more readable, and less prone to error.

Unused variables

The need to declare a variable that is never used is especially common in code whose side-effect is more important than its result. For example, this code calculates total as the side effect of a loop, without using the loop variable order:

static int total(Iterable<Order> orders) {
        int total = 0;
        for (Order order : orders)    // order is unused
            total++;
        return total;
    }

The prominence of the declaration of order is unfortunate, given that order is not used. The declaration can be shortened to var order, but there is no way to avoid giving this variable a name. The name itself can be shortened to, e.g., o, but this syntactic trick does not communicate the intent that the variable never be used. In addition, static analysis tools typically complain about unused variables, even when the developer intends non-use and may not have a way to silence the warnings.

For another example where the side effect of an expression is more important than its result, the following code dequeues data but needs only two out of every three elements:

static void processQueue(Queue<Integer> q) {
       while (q.size() >= 3) {
            int x = q.remove();
            int y = q.remove();
            int z = q.remove();   // z is unused
            new Point(x, y);
        }
    }

Do not declare the variable z, which leads to an asymmetry and possibly a static-analysis warning about ignoring a return value, or else

Declare a variable that is not used and possibly get a static-analysis warning about an unused variable.

Unused variables occur frequently in two other statements that focus on side effects:

The try-with-resources statement is always used for its side effect, namely the automatic closing of resources. In some cases a resource represents a context in which the code of the try block executes; the code does not use the context directly, so the name of the resource variable is irrelevant. For example, assuming a ScopedContext resource that is AutoCloseable, the following code acquires and automatically releases a context:

static void tryWithResourcesUnusedVaribale() {
        try (var acquiredContext = ScopedContext.acquire()) {
          //  acquiredContext not used
        }
    }

The name acquiredContext is just clutter, so it would be nice to elide it.

Exceptions are the ultimate side effect, and handling one often gives rise to an unused variable. For example, most developers have written catch blocks of this form, where the exception parameter ex is unused:

static void exceptionUnUsedVariable() {
        String s = "Un Used exception variable";
        try {
            int i = Integer.parseInt(s);
        } catch (NumberFormatException ex) {
            System.out.println("Bad number: " + s);
        }
    }

Even code without side effects must sometimes declare unused variables. For example:

static void lambdaUnUsedVariable() {
        List<String> list = new ArrayList<>();
        list.add("dummy");
        list.stream().collect(Collectors.toMap(String::toUpperCase,
                v -> "NODATA")); // v never used
    }

This code generates a map which maps each key to the same placeholder value. Since the lambda parameter v is not used, its name is irrelevant.

In all these scenarios, where variables are unused and their names are irrelevant, it would be better if we could simply declare variables with no name. This would free maintainers from having to understand irrelevant names, and would avoid false positives on non-use from static analysis tools.

The kinds of variables that can reasonably be declared with no name are those which have no visibility outside a method: local variables, exception parameters, and lambda parameters, as shown above. These kinds of variables can be renamed or made unnamed without external impact. In contrast, fields — even if they are private — communicate the state of an object across methods, and unnamed state is neither helpful nor maintainable.

Unused pattern variables

Local variables can also be declared by type patterns — such local variables are known as pattern variables — and so type patterns can also declare variables that are unused. Consider the following code, which uses type patterns in the case labels of a switch statement that switches over an instance of a sealed class Ball:

sealed public abstract class Ball permits RedBall, BlueBall, GreenBall { }
final  class RedBall   extends Ball { }
final  class BlueBall  extends Ball { }
final  class GreenBall extends Ball { }

static void switchCase(Ball ball) {
        switch (ball) {
            case RedBall red   -> process(ball); // red never used
            case BlueBall blue  -> process(ball); // blue never used
            case GreenBall green -> stopProcessing(); // green never used
        }
    }

The cases of the switch examine the type of the Ball using type patterns, but the pattern variables red, blue, and green are not used on the right-hand sides of the case clauses. This code would be clearer if we could elide these variable names.

Now suppose that we define a record class Box which can hold any type of Ball, but might also hold the null value:

record Box<T extends Ball>(T content) { }

static void nestedTypePatternUnUsed( Box<? extends Ball> box) {
        switch (box) {
            case Box(RedBall   red)     -> processBox(box); // red never used
            case Box(BlueBall  blue)    -> processBox(box); // blue never used
            case Box(GreenBall green)   -> stopProcessing(); // green never used
            case Box(var itsNull) -> pickAnotherBox(); // itsNull never used
        }
    }

The nested type patterns still declare pattern variables that are not used. Since this switch is more involved than the previous one, eliding the names of the unused variables in the nested type patterns would even further improve readability.

Unused nested patterns

We can nest records within records, leading to situations in which the shape of a data structure is as important as the data items within it. For example:

static void unUsedNestedPatterns() {
        record Point(int x, int y) { }
        enum Color { RED, GREEN, BLUE }
        record ColoredPoint(Point p, Color c) { }

        ColoredPoint r =  new ColoredPoint(new Point(3,4), Color.GREEN);

        if (r instanceof ColoredPoint(Point p, Color c)) {
                p.x();
                p.y();
        }
    }

In this code, one part of the program creates a ColoredPoint instance while another part uses a pattern instanceof to test whether a variable is a ColoredPoint and, if so, extract its two component values.

Record patterns such as ColoredPoint(Point p, Color c) are pleasingly descriptive, but it is common for programs to use only some of the component values for further processing. For example, the code above uses only p in the if block, not c. It is laborious to write out type patterns for all the components of a record class every time we do such pattern matching. Furthermore, it is not visually clear that the entire Color component is irrelevant; this makes the condition in the if block harder to read, too. This is especially evident when record patterns are nested to extract data within components, as in:

static void unUsedNestedPatterns() {
        record Point(int x, int y) { }
        enum Color { RED, GREEN, BLUE }
        record ColoredPoint(Point p, Color c) { }

        ColoredPoint r =  new ColoredPoint(new Point(3,4), Color.GREEN);

        if (r instanceof ColoredPoint(Point p, Color c)) {
                p.x();
                p.y();
        }

        if (r instanceof ColoredPoint(Point(int x, int y), Color c)) {
            System.out.println(x);
            System.out.println(y);
        }
    }

We could use an unnamed pattern variable to reduce the visual cost, e.g. ColoredPoint(Point(int x, int y), Color _), but the presence of the Color type in the type pattern is distracting. We could remove that by using var, e.g. ColoredPoint(Point(int x, int y), var _), but the nested type pattern var _ still has excessive weight. It would better to reduce the visual cost even further by omitting unnecessary components altogether. This would both simplify the task of writing record patterns and improve readability, by removing clutter from the code.

Java 22 - Solutions for unused variables

unnamed variable

An unnamed variable is declared by using an underscore character, _ (U+005F), to stand in for the name of the local variable in a local variable declaration statement, or an exception parameter in a catch clause, or a lambda parameter in a lambda expression

Declaring an unnamed variable does not place a name in scope, so the variable cannot be written or read after it is initialized. An initializer must be provided for an unnamed variable declared in a local variable declaration statement or in the resource specification of a try-with-resources statement.

An unnamed variable never shadows any other variable, since it has no name, so multiple unnamed variables can be declared in the same block.

Here are the examples given above, rewritten to use unnamed variables.

An enhanced for loop with side effects:

 static int count(Iterable<Order> orders) {
        int total = 0;
        for (Order _ : orders)    // Unnamed variable
            total++;
        return total;
    }

The initialization of a simple for loop can also declare unnamed local variables:

static void anotherExample() {
        for (int i = 0, _ = sideEffect(); i < 10; i++) {

        }
    }

An assignment statement, where the result of the expression on the right-hand side is not needed:

static void processQueue(Queue<Integer> q) {
        while (q.size() >= 3) {
            int x = q.remove();
            int y = q.remove();
            int _ = q.remove();  // Unnamed variable
            new Point(x, y);
        }
    }

If the program needed to process only the x coordinates then unnamed variables could be used in multiple assignment statements:

static void processQueue2(Queue<Integer> q) {
        while (q.size() >= 3) {
            int x = q.remove();
            int _ = q.remove();  // Unnamed variable
            int _ = q.remove();  // Unnamed variable
            new Point(x, 0);
        }
    }

A catch block:

static void tryWithResourcesUnNamedVariable() {
        try (var _ = ScopedContext.acquire()) { // Unnamed variable

        }
    }

Unnamed variables can be used in multiple catch blocks:

static void exceptionUnNamedVariable() {
        String s = "Un Used exception variable with unnamed variable";
        try {
            int i = Integer.parseInt(s);
        } catch (NumberFormatException _) {
            System.out.println("Bad number: " + s);
        }
    }

static void tryWithResourcesUnNamedVariable() {
        try (var _ = ScopedContext.acquire()) { // Unnamed variable

        }
    }

A lambda whose parameter is irrelevant:

static void lambdaUnUsedVariable() {
        List<String> list = new ArrayList<>();
        list.add("dummy");
        list.stream().collect(Collectors.toMap(String::toUpperCase,
                _ -> "NODATA")); // Unnamed variable
    }

unnamed pattern variable

An unnamed pattern variable can appear in a type pattern ( JLS §14.30.1 ), including var type patterns, regardless of whether the type pattern appears at the top level or is nested in a record pattern. For example, the Ball example can now be written:

static void switchCase(Ball ball) {
        switch (ball) {
            case RedBall _   -> process(ball);          // Unnamed pattern variable
            case BlueBall _  -> process(ball);          // Unnamed pattern variable
            case GreenBall _ -> stopProcessing();       // Unnamed pattern variable
        }
    }

and the Box and Ball example:

 static void nestedTypePatternUnUsed( Box<? extends Ball> box) {
        switch (box) {
            case Box(RedBall _)   -> processBox(box);   // Unnamed pattern variable
            case Box(BlueBall _)  -> processBox(box);   // Unnamed pattern variable
            case Box(GreenBall _) -> stopProcessing();  // Unnamed pattern variable
            case Box(var _)       -> pickAnotherBox();  // Unnamed pattern variable
        }
    }

By allowing us to elide names, unnamed pattern variables make run-time data exploration based on type patterns visually clearer, both in switch blocks and with the instanceof operator.

Multiple patterns in case labels
Currently, case labels are restricted to contain at most one pattern. With the introduction of unnamed pattern variables and unnamed patterns, it is more likely that we will have within a single switch block several case clauses with different patterns but the same right-hand side. For example, in the Box and Ball example the first two clauses have the same right-hand side but different patterns.

We could simplify matters by allowing the first two patterns to appear in the same case label

static void multiplePatternsInCaseLabels(Box<? extends Ball> box) {
        switch (box) {
            case Box(RedBall _), Box(BlueBall _) -> processBox(box);
            case Box(GreenBall _)                -> stopProcessing();
            case Box(var _)                      -> pickAnotherBox();
        }
    }

We therefore revise the grammar for switch labels (JLS §14.11.1) to

SwitchLabel:
    case CaseConstant {, CaseConstant}
    case null [, default]
    case CasePattern {, CasePattern } [Guard]
    default

and define the semantics of a case label with multiple patterns as matching a value if the value matches any of the patterns.

If a case label has multiple patterns then it is a compile-time error for any of the patterns to declare any pattern variables.

A case label with multiple case patterns can have a guard. The guard governs the case as a whole, rather than the individual patterns. For example, assuming that there is an int variable x, the first case of the previous example could be further constrained:

case Box(RedBall _), Box(BlueBall _) when x == 42 -> processBox(b);

Guards are properties of case labels, not individual patterns within a case label, so writing more than one guard is prohibited:

case Box(RedBall _) when x == 0, Box(BlueBall _) when x == 42 -> processBox(b);
    // compile-time error

The unnamed pattern

The unnamed pattern is an unconditional pattern that matches anything but declares and initializes nothing. Like the unnamed type pattern var _ , the unnamed pattern can be nested in a record pattern. It cannot, however, be used as a top-level pattern in, e.g., an instanceof expression or a case label.

Consequently, the earlier example can omit the type pattern for the Color component entirely:

static void unNamedPattern() {
        record Point(int x, int y) { }
        enum Color { RED, GREEN, BLUE }
        record ColoredPoint(Point p, Color c) { }

        ColoredPoint r =  new ColoredPoint(new Point(3,4), Color.GREEN);

        if (r instanceof ColoredPoint(Point(int x, int y), _)) {
            System.out.println(x);
            System.out.println(y);
        }
    }

Likewise, we can extract the Color component value while eliding the record pattern for the Point component:

if (r instanceof ColoredPoint(_, Color c)) {
            c.name();
 }

In deeply nested positions, using the unnamed pattern improves the readability of code that does complex data extraction. For example:

if (r instanceof ColoredPoint(Point(int x, _), _)) {
            System.out.println(x);
 }

This code extracts the x coordinate of the nested Point while making it clear that the y and Color component values are not extracted.

Revisiting the Box and Ball example, we can further simplify its final case label by using the unnamed pattern instead of var _:

static void multiplePatternsInCaseLabels(Box<? extends Ball> box) {
        switch (box) {
            case Box(RedBall _), Box(BlueBall _) -> processBox(box);
            case Box(GreenBall _)                -> stopProcessing();
            case Box(_)                      -> pickAnotherBox();
        }
    }

Risks and Assumptions

We assume that little if any actively-maintained code uses underscore as a variable name. Developers migrating from Java 7 to Java 22 without having seen the warnings issued in Java 8 or the errors issued since Java 9 could be surprised. They face the risk of dealing with compile-time errors when reading or writing variables named _ and when declaring any other kind of element (class, field, etc.) with the name _.

We expect developers of static analysis tools to understand the new role of underscore for unnamed variables and avoid flagging the non-use of such variables in modern code.

The complete source code for the example is available in this GitHub project. This is a Maven and Eclipse project, so it can be imported and used as is.

Further Reading:

Explore More

Unnamed Variables & Patterns in Java 22 with practical example