kotlin-control-flow

Kotlin control flow

Purpose

Use this skill to write or review the shape of Kotlin branching code. Treat it as a refactoring procedure, not as a style preference.

The target state is simple: the classified value is obvious, branch-local predicates stay with their branch, smart casts remain usable, and the compiler proves exhaustiveness for closed domains.

Procedure

Apply these checks in order.

1. Name the subject

Find the value the code is classifying. If every branch asks a question about the same value, make that value the when subject.

// Replace repeated checks against `state` with a subject `when`.
val action = when (state) {
    State.SignedOut -> Action.ShowSignIn
    is State.SignedIn -> Action.ShowHome(state.user)
}

If there is no single subject, keep a subjectless when or an if chain.

2. Pick the branch primitive

Use this decision table before editing:

If the code has...	Use...
One value being classified	when (subject)
Unrelated boolean conditions	Subjectless when or if/else
A primary match plus an extra branch-local predicate	Guard condition
Invalid input before the main path	Early return, require, or check
A closed enum, Boolean, sealed type, or nullable closed type returning a value	Exhaustive when expression
Open external input or a real fallback	Explicit else

3. Move branch-local predicates into guard conditions

When a branch first matches a type/value and then checks an extra predicate, use a guard condition (requires the Kotlin version in gradle/libs.versions.toml — see ../../reference/coding-conventions.md for this project's pinned language level):

return when (event) {
    is Event.Message if event.isUnread -> Row.Highlighted(event.message)
    is Event.Message -> Row.Normal(event.message)
    Event.Empty -> Row.Empty
}

Apply guards only when all of these are true:

• The when has a subject.
• The branch has a primary condition (is Type, enum entry, object, value, range, etc.).
• The extra condition belongs only to that branch.
• A later branch still handles the same primary condition, or the expression remains exhaustive some other way.