Why is this an issue?

It is a common pattern to validate required preconditions at the beginning of a function or block. There are two different kinds of preconditions:

Preconditions about argument values. An example is the assertion that a function argument lies within a specific range. An IllegalArgumentException should be thrown if these preconditions are violated.
Preconditions about the state of the owner or the execution context of the function. An example is when a specific method, such as open, init or prepare, must be called before the current method can be executed. An IllegalStateException should be thrown if these preconditions are violated.

The Kotlin standard library provides the functions check(), require(), checkNotNull() and requireNotNull() for this purpose. They should be used instead of directly throwing an IllegalArgumentException or an IllegalStateException.

What is the potential impact?

Readability and Understanding

This change makes it easier to understand the code because the semantics of check(), require(), checkNotNull() and requireNotNull(), as well as the fact that this is a preconditions check, are evident to the reader. When developers share common standards and idioms, they need to spend less effort understanding each other’s code.

Code Redundancy

Using a built-in language feature or a standard API is always better than a custom implementation, because the reimplementation of something that already exists is unnecessary.

Consistency

When check(), require(), checkNotNull() and requireNotNull() are used in an idiomatic way, there is more consistency in what kind of exception is thrown in which situation.

How to fix it

Replace	With
`if (!condition) throw IllegalArgumentException()`	`require(condition)`
`if (reference == null) throw IllegalArgumentException()`	`requireNotNull(reference)`
`require(reference != null)`	`requireNotNull(reference)`
`if (!condition) throw IllegalStateExceptionException()`	`check(condition)`
`if (reference == null) throw IllegalStateException()`	`checkNotNull(reference)`
`check(reference != null)`	`checkNotNull(reference)`
`throw IllegalStateException()`	`error()`

A constructor function for the exception message can be provided as an optional argument for check(), require(), checkNotNull() and requireNotNull(). This means the message is constructed only if the exception is thrown. For the error() function, an optional error message parameter can be provided directly. That is, without a parameter, because an exception is unconditionally thrown by error().

Code examples

Noncompliant code example

fun argumentPreconditions(argument: Int?, limit: Int?) {
    if (argument == null) throw IllegalArgumentException() // Noncompliant, replace with requireNotNull
    require(limit != null)  // Noncompliant, replace with requireNotNull
    if (argument < 0) throw IllegalArgumentException()  // Noncompliant, replace with require
    if (argument >= 0) throw IllegalArgumentException("Argument < $limit") // Noncompliant, replace with require
}

Compliant solution

fun argumentPreconditions(argument: Int?, limit: Int?) {
    requireNotNull(argument) // Compliant
    requireNotNull(limit) // Compliant
    require(argument >= 0) // Compliant
    require(argument < limit) {"Argument < $limit"} // Compliant
}

Noncompliant code example

fun statePreconditions() {
    if (state == null) throw IllegalStateException() // Noncompliant, replace with checkNotNull
    check(ioBuffer != null)  // Noncompliant, replace with checkNotNull
    if (state < 0) throw IllegalStateException()  // Noncompliant, replace with check
    if (state == 42) throw IllegalStateException("Unknown question") // Noncompliant, replace with check

    when(state) {
        0..10 -> processState1()
        11..1000 -> processState2()
        else -> throw IllegalStateException("Unexpected state $state") // Noncompliant, replace with error
    }
}

Compliant solution

fun statePreconditions() {
    checkNotNull(state) // Compliant
    checkNotNull(ioBuffer) // Compliant
    check(state >= 0) // Compliant
    check(state != 42) {"Unknown question"} // Compliant

    when(state) {
        0..10 -> processState1()
        11..1000 -> processState2()
        else -> error("Unexpected state $state") // Compliant
    }
}

Resources

Documentation

Articles & blog posts

Jeremy W. Sherman, Write Better Code Using Kotlin’s Require, Check and Assert