Effective Kotlin Item 7: Prefer a nullable or Result result type when the lack of a result is possible
Sometimes a function cannot produce its desired result. A few common examples are:
- We try to get data from a server, but there is a problem with the internet connection.
- We try to get the first element that matches some criteria, but there is no such element in our list.
- We try to parse an object from text, but this text is malformatted.
There are two main mechanisms to handle such situations:
- Return a
Result.failure, thus indicating failure.
- Throw an exception.
There is an important difference between these two. Exceptions should not be used as a standard way to pass information. All exceptions indicate incorrect, special situations and should be treated this way. We should use exceptions only for exceptional conditions (Effective Java by Joshua Bloch). The main reasons for this are:
- The way exceptions propagate is not very readable for most programmers and might easily be missed in code.
- In Kotlin, all exceptions are unchecked. Users are not forced or even encouraged to handle them. They are often not well documented, and they are not very visible when we use an API.
- Because exceptions are designed for exceptional circumstances, there is little incentive for JVM implementers to make them as fast as explicit tests.
- Placing code inside a try-catch block inhibits certain optimizations that the compiler might otherwise perform.
It is worth mentioning that exceptions are used by some popular patterns, like on backend, exceptions are used to end request processing and respond to requester with a specific response code and message. Similarly on Android, exceptions are sometimes used to end a process and display a concrete dialog or toast to the user. In such cases, many of my arguments against exceptions do not apply, and using exceptions could be reasonable.
On the other hand,
Result.failure are both perfect for indicating an expected error. They are explicit, efficient, and can be handled in idiomatic ways. This is why the rule is that we should prefer to return
Result.failure when an error is expected, and we should throw an exception when an error is not expected. Here are some examples:
Result result type
We use the
Result class from the Kotlin stdlib to return a result that can be either a success or a failure. Failure includes an exception, that keeps the information about the error. We use
Result instead of nullable type in functions that need to pass additional information in the case of failure. For example, when we implement a function that is fetching information from the internet,
Result should be preferred over
null, because we can pass the information about the error, like the error code or the error message.
When we choose to return
Result, the user of this function will be able to handle it using methods from the
Using such error handling is simpler than using a try-catch block. It is also safer, because an exception can be missed and can stop our whole application; in contrast, a
null value or a
Result object needs to be explicitly handled, and it won’t interrupt the flow of the application.
The difference between a nullable result and the
Result object is that we should prefer the latter when we need to pass additional information in the case of failure; otherwise, we should prefer
Result class has a rich API of methods you can use to handle your result, including:
isFailureproperties, which we use to check if the result represents a success or a failure (
isSuccess == !isFailureis always true).
onFailuremethods, which call their lambda expressions when the result is, respectively, a success or a failure.
getOrNullmethod, which returns the value if the result is a success, or
getOrThrowmethod, which returns the value if the result is a success, or throws the exception from the failure otherwise.
getOrDefaultmethod, which returns the value if the result is a success, or the default value provided as an argument if the result is a failure.
getOrElsemethod, which returns the value if the result is a success, or calls its functional argument and returns its result.
exceptionOrNullmethod, which returns the exception if the result is a failure, or
mapmethod for transforming the success value.
recovermethod for transforming a throwable value into a success value.
foldmethod for handling both success and failure in a single method.
To transform a function that throws exceptions into one that returns
null result type
null is a marker of a lack of value. When a function returns
null, it means that it cannot return a value. For example:
nullwhen there is no value at the given index.
Stringcannot be correctly parsed to
Iterable<T>.firstOrNull(() -> Boolean)returns
nullwhen there are no elements matching the predicate from the argument.
As you can see,
null is used to indicate that a function cannot return the expected value. We use nullable type instead of
Result in functions that do not need to pass additional information in the case of failure, where the meaning of
null is clear. In the function
String.toIntOrNull(), it is clear that
null means that the string cannot be parsed to
Int. In the function
Iterable<T>.firstOrNull(() -> Boolean), it is clear that
null means that there are no elements matching the predicate. For all functions that return
null, the meaning of
null should be clear.
Nullable value needs to be unwrapped before it can be used. For dealing with them, Kotlin offers us many useful features, like the safe call operator
?., the Elvis operator
?:, and smart casting.
Null is our friend, not an enemy
Many Kotlin developers are ex-Java developers, who are thought to treat
null like an enemy. For example, in Effective Java (2nd edition), Joshua Bloch presents Item 43: Return empty arrays or collections, not nulls. Such a suggestion would be absurd in Kotlin. An empty collection has a completely different meaning than
null. Imagine we called the function
getUsers: if it returned
null, this would mean it couldn’t produce a value, so we still don’t know what the answer is; in contrast, if it returned an empty collection, this would mean that there are no users. These are different results, and they should not be confused. Kotlin's type system lets us express what is nullable and what is not, and it forces us to handle nulls consciously. We should not be afraid of nulls: we should embrace them and use them to express our intentions. Forget about all the suggestions to avoid nulls because they are not applicable in Kotlin. In Kotlin,
null is our friend, not an enemynull-friend.
Defensive and offensive programming
In Item 5: Specify your expectations for arguments and state, I explained that we should throw exceptions to signal incorrect arguments or states, and in this item, I explained that we should in general avoid throwing exceptions and prefer returning
Result or nullable types instead. These two statements seem to be in conflict, but they are not, because they refer to different kinds of situations.
Exceptions should not be part of our regular program execution flow; so, when you perform an operation that might either succeed or fail, like fetching data from a database or network, you should use
Result or nullable types. This forces the developer to handle the failure case explicitly. Since it is part of the regular program execution flow, it is best to handle such a situation safely so all possible situations are handled correctly. This is an implementation of the defensive programming idea.
On the other hand, when a developer makes a mistake, like calling a method with incorrect arguments or calling a method on an object in an incorrect state, silencing such a situation would be dangerous because our program has encountered a situation that is clearly unexpected. We should loudly signal this situation so our program can be corrected. This is an implementation of the offensive programming idea.
Defensive and offensive programming do not contradict each other; they are more like yin and yang: different techniques that are both needed in our programs for the sake of safety, so we need to understand and use both of them appropriately.
- When a function can fail, we should return
Resultor a nullable type instead of throwing an exception.
- We should use
Resultwhen we need to pass additional information in the case of failure.
- We should use a nullable type when the meaning of
- We should not be afraid of nulls: we should embrace them and use them to express our intentions.
- We should use defensive programming to handle regular program execution flow, while offensive programming should be used to handle unexpected situations.
This is possible because both
Nothing as a return type that is a subtype of every type. More about this here: kt.academy/article/kfde-type_system