Effective Kotlin Item 34: Consider a primary constructor with named optional arguments
This is a chapter from the book Effective Kotlin. You can find it on LeanPub or Amazon.
When we define an object and specify how it can be created, the most popular option is to use the primary constructor:
Not only are primary constructors very convenient, but in most cases it is actually very good practice to build objects using them. It is common that we need to pass arguments that determine an object’s initial state, as illustrated by the following examples, starting from the most obvious one: data model objects that represent data1. For such an object, its whole state is initialized using a constructor and then held as properties.
Here’s another common example in which we create a presenter2 for displaying a sequence of indexed quotes. We inject dependencies into this object using a primary constructor3:
QuotationPresenter has more properties than those declared in the primary constructor. Here,
nextQuoteId is a property that is always initialized with the value
-1. This is perfectly fine, especially when the initial state is set up using default values or primary constructor parameters.
To better understand why the primary constructor is such a good choice in the majority of cases, we must first consider common Java patterns related to the use of constructors:
- the telescoping constructor pattern
- the builder pattern
We will see the problems that these solve and the better alternatives that Kotlin offers.
Telescoping constructor pattern
The telescoping constructor pattern is nothing more than a set of constructors for different possible sets of arguments:
Well, this code doesn't really make any sense in Kotlin because we can use default arguments instead:
Default values are not only cleaner and shorter, but their usage is also more powerful than the telescoping constructor. We can specify just
olives without mentioning other parameters:
We can also add another named argument either before or after olives:
As you can see, default arguments are more powerful than the telescoping constructor because:
- We can define a subset of parameters with the default arguments we want.
- We can provide arguments in any order.
- We can explicitly name arguments to make it clear what each value means.
The last reason is quite important. Think of the following object creation:
It is short, but is it clear? I bet that even the person who declared the pizza class won’t remember the positions of the bacon and cheese parameters. Sure, in an IDE we can see an explanation, but what about those who just scan code or read it on Github? When arguments are unclear, we should explicitly state what their names are using named arguments:
As you can see, constructors with default arguments surpass the telescoping constructor pattern. However, there are more popular construction patterns in Java, one of which is the Builder Pattern.
Named parameters and default arguments are not allowed in Java. This is the main reason why Java developers use the builder pattern, which allows them to:
- name parameters,
- specify parameters in any order,
- have default values.
Here is an example of a builder defined in Kotlin:
With the builder pattern, we can set these parameters as we want by using their names:
As we’ve already mentioned, these advantages of Java’s builder pattern are fully satisfied by Kotlin’s named and default arguments:
When comparing these two simple usages, you can see the advantages of named parameters over the builder:
Named parameters are shorter — a constructor or factory method with default arguments is much easier to implement than the builder pattern. It is a time-saver both for the developer who implements this code and for those who read it. This is a significant difference because implementation of the builder pattern can be time-consuming. Builder modifications are harder to apply. For instance, changing the name of a parameter requires not only changing the name of the function used to set it but also the name of the parameter in this function, the body of this function, the internal field used to keep it, the parameter name in the private constructor, etc.
Named parameters are cleaner — when you want to see how an object is constructed, everything you need is in a single method instead of being scattered around a whole builder class. How are objects held? Do they interact? These are questions that are not so easy to answer when we have a big builder.
Named parameters offer simpler usage — the primary constructor is a built-in concept. The builder pattern is an artificial concept and therefore requires some knowledge about it. For instance, a developer can easily forget to call the
buildfunction (or, in other cases,
Named parameters have no problems with concurrence — this is a rare problem, but function parameters are always immutable in Kotlin, while properties in most builders are mutable. Therefore, it is harder to implement a thread-safe build function for a builder.
All this doesn't mean that we should always use a constructor instead of a builder, so let’s look at some cases where the various advantages of the builder pattern shine.
Builders can require a set of values for a name (
addRoute), and they allow us to aggregate (
To achieve similar behavior with a constructor, we would need to introduce special types to hold more data in a single argument:
This notation is generally badly received in the Kotlin community and we tend to prefer a DSL (Domain Specific Language) builder for such cases:
These kinds of DSL builders are generally preferred over the classic Builder pattern since they give more flexibility and cleaner notation, but it is true that making a DSL is harder. On the other hand, making a builder is already hard. If we decide to invest more time to allow better notation at the cost of a less obvious definition, why not take this one step further? In return, we will have more flexibility and readability. In the next chapter, we talk more about using DSLs for object creation.
Another advantage of the classic Builder pattern is that it can be used as a factory that might be filled partially and passed further. Here is a partially filled example builder that is used to specify a default dialog in our application:
The alternatives I find more suitable in Kotlin are either making a default object and using
copy to customize its properties, or creating this class using a function with optional parameters.
Both options seem to be popular for unit testing. They seem to be a good alternative to the classic Builder pattern, so I don't find the Builder pattern advantageous.
In the end, the classic Builder pattern is rarely the best option in Kotlin. It is sometimes chosen:
- to make code consistent with libraries written in other languages that used the Builder pattern,
- when we design an API to be easily used in other languages that do not support default arguments or DSLs.
Otherwise, we generally prefer either a primary constructor with default arguments or an expressive DSL builder.
Creating objects using a primary constructor is the most appropriate approach for the vast majority of objects in our projects. Telescoping constructor patterns should be treated as obsolete in Kotlin. I recommend using default values instead as they are cleaner, more flexible, and more expressive. The classic builder pattern is rarely a good choice. In simpler cases, we can just use a primary constructor with named arguments; when we need to create a more complex object, we can define a DSL builder.
A data model is not necessarily a data class, and vice versa. The former concept represents classes in our project that represent data, while the latter is special support for such classes. This special support is a set of functions that we might not need or that we might need for classes that do not serve as our data model.
A presenter is a kind of object that is used in the Model View Presenter (MVP) architecture, which used to be popular in Android before its successor MVVM became popular.
Dependency injection is a technique in which an object receives other objects that it depends on. By itself, it does not need any library (or framework) like Koin or Dagger, although I find them useful.