How Immutability makes software easier to understand

There has been a trend in Java towards adding more support for immutable data structures. What is an immutable data structure and why should you use one ?

An immutable data structure is simply a data structure- an object or collection of objects- that can’t be modified. Immutable data structures make programs simpler and easier to understand. If we know that the value of an object can never change, we don’t need to think about when it might change or what might happen if it does.

Consider the following Java code:

List<String> list = new ArrayList<>();
list.add(“test”);
mystery_function(list);
System.out.println(“list is ” + list);

What gets printed ? Without reading through the code for mystery_function, we have no way of knowing because we don’t know whether or how mystery_function modifies list.

Let’s replace ArrayList with Google’s ImmutableList:

List<String> list = ImmutableList.of(“test”);
mystery_function(list);
System.out.println(“list is ” + list);

Now the output is obvious because we know that list will only ever contain the single value “test” and can’t be changed.

What if instead of using ImmutableList we just make a copy of the list ?

List<String> list = new ArrayList<>();
list.add(“test”);
mystery_function(new ArrayList<>(list));
System.out.println(“list is ” + list);

now mystery_function can’t modify list because it only gets a copy of list, not list itself. Problem solved, right ?

Not necessarily. Yes, we now know what the println statement above will output but we’ve really just kicked the can down the road.

mystery_function still receives a modifiable list, so without carefully inspecting the code (which might be thousands of lines) there’s no way to know whether the value of the list at one point in time as the same as at another point in time.

Java 9 introduced the List.of(), Map.of() and Set.of() methods that return immutable collections. Great! So doesn’t that make Google’s immutable collections obsolete ?

No. The type returned by List.of() is just a List. There is no way to tell whether it is immutable except by trying to modify it and seeing whether it throws an exception, an expensive operation.

With Google’s immutable collections, we can use the instanceof operator, which is much cheaper:

if (collection instanceof ImmutableCollection) {
   ...
}

And if we want to ensure a list is Immutable we can use

ImmutableList immutableList = ImmutableList.copyOf(list);

If list is already an ImmutableList then ImmutableList.cppyOf(list) just returns list -very efficient!

By declaring all of your collections as ImmutableList, ImmutableSet, ImmutableMap or ImmutableCollection except where they need to be mutable the reader can immediately tell whether a collection is likely to be modified or not without having to rely on comments which might be missing or out of date, or a time-consuming analysis of the code.