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.
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:
Errors indicated like this are easier to handle and harder to miss. When we choose to use
null, clients handling such a value can choose from a variety of null-safety-supporting features like a safe-call or the Elvis operator:
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 not only more efficient than a try-catch block but is often also easier to use and more explicit. 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
In important parts of an API, you might define two variants of functions: one that expects that failure can occur, and one that treats it as an unexpected situation. A good example is the fact that
List has both:
get, which is used when we expect an element to be at the given position; if it is not there, the function throws
getOrNull, which is used when we suppose that we might ask for an element that is out of range; if that happens, we’ll get
List also supports other options, like
getOrDefault, which is useful in some cases but in general might be easily replaced with
getOrNull and the Elvis operator
This is good practice because if developers know that an element must be at the specific position, they should not be forced to handle a nullable value; if they have any doubts, they should use
getOrNull and properly handle the lack of a value.