Preconditions (require, check, error) in Kotlin - Deep Dive

Overview - Preconditions (require, check, error)

What is it?

Preconditions in Kotlin are ways to check if certain conditions are true before continuing with the program. They help catch mistakes early by stopping the program if something is wrong. The main functions are require, check, and error, which throw exceptions when conditions fail. This helps keep the program safe and predictable.

Why it matters

Without preconditions, programs might continue running with wrong or unexpected data, causing bugs or crashes later. Preconditions catch problems right where they happen, making it easier to find and fix errors. This saves time and prevents confusing failures in bigger parts of the program.

Where it fits

Before learning preconditions, you should understand basic Kotlin syntax, functions, and exceptions. After mastering preconditions, you can learn about advanced error handling, custom exceptions, and defensive programming techniques.

Mental Model

Core Idea

Preconditions are safety checks that stop the program immediately if something important is wrong, preventing bigger problems later.

Think of it like...

It's like a safety inspector checking a machine before it starts. If something is broken, the inspector stops the machine from running to avoid accidents.

┌───────────────┐
│ Start Program │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Check Condition│
└──────┬────────┘
       │True
       ▼
┌───────────────┐
│ Continue Work │
└───────────────┘
       │
       │False
       ▼
┌───────────────┐
│ Throw Exception│
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Preconditions Purpose

Concept: Preconditions are checks that make sure inputs or states are correct before running code.

Imagine you have a function that divides two numbers. You want to make sure the divisor is not zero before dividing. Preconditions help you check this and stop if the divisor is zero.

Result

If the divisor is zero, the program stops immediately with an error instead of crashing later.

Knowing why preconditions exist helps you write safer code that fails early and clearly.

2

Foundation

Basic Usage of require Function

Concept: The require function checks a condition and throws an IllegalArgumentException if false.

fun divide(a: Int, b: Int): Int { require(b != 0) { "Divisor must not be zero" } return a / b } Calling divide(10, 0) stops with an error message.

Result

Calling divide(10, 0) throws IllegalArgumentException with message "Divisor must not be zero".

require is a simple way to check input arguments and give clear error messages.

3

Intermediate

Using check for Internal State Validation

🤔Before reading on: do you think require and check behave the same way? Commit to your answer.

Concept: The check function verifies internal program state and throws IllegalStateException if false.

class Counter { var count = 0 fun increment() { count++ check(count <= 10) { "Count cannot exceed 10" } } } If count goes above 10, check stops the program.

Result

If increment is called more than 10 times, IllegalStateException is thrown with message "Count cannot exceed 10".

Understanding the difference between require (input checks) and check (state checks) helps organize your code's safety.

4

Intermediate

Throwing Errors Explicitly with error Function

🤔Before reading on: do you think error function requires a condition to throw an exception? Commit to your answer.

Concept: The error function immediately throws an IllegalStateException with a message, without checking a condition.

fun failFast(): Nothing { error("This function always fails") } Calling failFast stops the program right away.

Result

Calling failFast throws IllegalStateException with message "This function always fails".

Knowing error lets you stop execution immediately when something unexpected happens.

5

Intermediate

Custom Messages for Clear Errors

Concept: You can add messages to require, check, and error to explain why the program stopped.

require(x > 0) { "x must be positive, but was $x" } check(state.isValid) { "State is invalid" } error("Unexpected error occurred")

Result

When conditions fail, the error messages help quickly understand the problem.

Clear messages make debugging faster and reduce confusion.

6

Advanced

Preconditions in Library and API Design

🤔Before reading on: do you think preconditions are only useful for small programs? Commit to your answer.

Concept: Preconditions are essential in libraries and APIs to enforce correct usage and prevent misuse by users.

A library function might use require to check user input and check to verify internal consistency. This prevents bugs from spreading to users' code.

Result

APIs fail fast with clear errors if used incorrectly, improving reliability and user trust.

Knowing how preconditions protect APIs helps you design robust, user-friendly libraries.

7

Expert

Performance and Exception Cost Considerations

🤔Before reading on: do you think precondition checks always run in production code? Commit to your answer.

Concept: Precondition checks add runtime cost and exceptions are expensive; sometimes they are disabled or minimized in production.

In Kotlin, require and check always run, but in some systems, assertions can be disabled. Understanding when to use preconditions versus other checks is key for performance.

Result

Balancing safety and speed avoids slowing down critical code while keeping it reliable.

Knowing the cost of checks helps you write efficient code without sacrificing safety.

Under the Hood

Preconditions like require and check evaluate a Boolean condition. If false, they throw an exception immediately, stopping the current function and unwinding the call stack until caught or program ends. require throws IllegalArgumentException, signaling bad input. check throws IllegalStateException, signaling wrong program state. error always throws IllegalStateException without condition. These exceptions carry messages to explain the failure.

Why designed this way?

Kotlin's preconditions follow a clear separation: require for input validation, check for internal state, and error for immediate failure. This design helps developers quickly identify the source of errors. Using exceptions allows the program to stop safely and report problems clearly. Alternatives like returning error codes were rejected because they are less safe and harder to track.

┌───────────────┐
│ Condition?    │
├───────────────┤
│ true          │
│   │           │
│   ▼           │
│ Continue Code │
│               │
│ false         │
│   │           │
│   ▼           │
│ Throw Exception│
│ (IllegalArgument│
│  or IllegalState)│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does require check internal program state or input arguments? Commit to your answer.

Common Belief: require and check are the same and can be used interchangeably.

Reality: require is meant for checking input arguments, while check is for verifying internal program state.

Why it matters: Using require for state checks or check for inputs can confuse error sources and make debugging harder.

Quick: Does error function check a condition before throwing? Commit to your answer.

Common Belief: error function works like require or check and only throws if a condition is false.

Reality: error immediately throws an exception without any condition; it always stops execution.

Why it matters: Misusing error can cause unexpected program stops and make code harder to read.

Quick: Do precondition checks slow down production code significantly? Commit to your answer.

Common Belief: Precondition checks are free and have no performance cost.

Reality: Precondition checks add runtime overhead and exceptions are costly; they should be used wisely.

Why it matters: Ignoring performance cost can lead to slow programs, especially in tight loops or critical code.

Quick: Can preconditions replace all error handling in Kotlin? Commit to your answer.

Common Belief: Preconditions are enough to handle all errors in a program.

Reality: Preconditions only check conditions early; full error handling requires try-catch and recovery strategies.

Why it matters: Relying only on preconditions can cause crashes instead of graceful error handling.

Expert Zone

1

require and check exceptions differ in type, which helps tools and developers identify error origin quickly.

2

Preconditions should be side-effect free to avoid unexpected behavior when conditions are checked multiple times.

3

In Kotlin contracts, preconditions can be combined with contracts to help the compiler understand code flow and optimize.

When NOT to use

Preconditions are not suitable for handling recoverable errors or user input validation that requires user feedback. Instead, use try-catch blocks, validation libraries, or result types like Either or Result for graceful error handling.

Production Patterns

In production, preconditions are used to catch programmer errors early during development and testing. Some teams disable or minimize checks in hot code paths for performance. Libraries use require for public API input validation and check for internal consistency. error is used for unreachable code or fatal errors.

Connections

Assertions

Preconditions are similar to assertions but differ in usage and exception types.

Understanding assertions helps grasp preconditions as checks that can be enabled or disabled depending on environment.

Defensive Programming

Preconditions are a core tool in defensive programming to prevent invalid states.

Knowing defensive programming principles shows why preconditions improve code robustness and maintainability.

Quality Control in Manufacturing

Preconditions act like quality checks in manufacturing to stop faulty products early.

Seeing preconditions as quality gates helps appreciate their role in preventing bigger failures.

Common Pitfalls

#1 Using require to check internal state instead of input arguments.

Wrong approach:

fun process(state: State) {
require(state.isValid) { "State invalid" }
// ...
}

Correct approach:

fun process(state: State) {
check(state.isValid) { "State invalid" }
// ...
}

Root cause:

Confusing the purpose of require and check leads to unclear error semantics.

#2 Calling error without a clear message or condition.

Wrong approach:

fun fail() {
error("")
}

Correct approach:

fun fail() {
error("Unexpected failure occurred")
}

Root cause:

Not providing meaningful messages makes debugging difficult.

#3 Overusing preconditions in performance-critical loops.

Wrong approach:

for (i in 1..1000000) {
require(i > 0)
// heavy computation
}

Correct approach:

require(i > 0) // check once before loop
for (i in 1..1000000) {
// heavy computation
}

Root cause:

Not understanding the runtime cost of repeated checks causes slow code.

Key Takeaways

Preconditions are checks that stop the program early if inputs or states are wrong, preventing bigger problems.

require is for input validation and throws IllegalArgumentException; check is for internal state and throws IllegalStateException.

error immediately throws an exception without checking a condition, used for fatal errors.

Clear error messages in preconditions help debugging and improve code clarity.

Using preconditions wisely balances safety and performance, especially in production code.