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.
kotlin
// 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 classifiedwhen (subject)
Unrelated boolean conditionsSubjectless when or if/else
A primary match plus an extra branch-local predicateGuard condition
Invalid input before the main pathEarly return, require, or check
A closed enum, Boolean, sealed type, or nullable closed type returning a valueExhaustive when expression
Open external input or a real fallbackExplicit 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:
kotlin
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.
Put guarded branches before their unguarded fallback for the same primary condition.

4. Preserve exhaustiveness

For a when expression over a closed domain, handle every case explicitly. Do not add else only to quiet the compiler.
Match singleton objects by value, but match class and data-class subtypes with is. In a subtype branch, use any caller-visible payload that the mapping already needs so the smart cast remains explicit; do not replace else with an invalid bare class name or discard subtype data merely to claim exhaustiveness.
kotlin
val action = when (state) {
    SessionState.SignedOut -> Action.ShowSignIn
    is SessionState.SignedIn -> Action.ShowHome(state.user)
    is SessionState.Expired if state.canRefresh -> Action.Refresh
    is SessionState.Expired -> Action.ShowSignIn
}
Use else when the domain is open: strings from a server, integer status codes, unknown platform values, or a deliberate fallback/logging path.

5. Split unsupported guarded branches

Guard conditions do not apply to comma-separated branch conditions. If only one case needs an extra predicate, split the branch:
kotlin
when (status) {
    Status.Pending if canRetry -> retry()
    Status.Pending -> showPending()
    Status.Queued -> showQueued()
}

6. Flatten invalid preconditions

Use early returns when they remove nullable or invalid state from the main path:
kotlin
fun render(user: User?): UiModel {
    user ?: return UiModel.SignedOut

    return UiModel.SignedIn(
        name = user.name,
        avatar = user.avatar,
    )
}
Do not flatten if nesting is carrying cleanup, transaction, or error-handling structure.

7. Check smart casts

After reshaping, verify that every branch still has the narrowed type available where it is used. If the rewrite forces as, !!, temporary mutable vars, or duplicated casts, keep the original shape or choose a smaller refactor.

Rewrite recipes

Nested branch inside when

When the nested branch only refines one primary case, convert it to guarded branches:
kotlin
// Before
return when (event) {
    is Event.Message -> {
        if (event.isUnread) Row.Highlighted(event.message) else Row.Normal(event.message)
    }
    Event.Empty -> Row.Empty
}

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

Repeated checks against one value

When every condition classifies the same value, make it the subject:
kotlin
// Before
return when {
    result is Result.Success -> Ui.Success(result.value)
    result is Result.Failure && result.canRetry -> Ui.Retry(result.error)
    result is Result.Failure -> Ui.Error(result.error)
    else -> Ui.Loading
}

// After
return when (result) {
    is Result.Success -> Ui.Success(result.value)
    is Result.Failure if result.canRetry -> Ui.Retry(result.error)
    is Result.Failure -> Ui.Error(result.error)
    Result.Loading -> Ui.Loading
}

Null as one case among several

Use when (value) when null is one branch in a larger classification:
kotlin
return when (val selected = selection) {
    null -> SelectionUi.None
    is Selection.Single if selected.item.isArchived -> SelectionUi.Archived(selected.item)
    is Selection.Single -> SelectionUi.Active(selected.item)
    is Selection.Multiple -> SelectionUi.Count(selected.items.size)
}

Review checklist

Before finishing a control-flow change, verify:
  • The code has one obvious subject, or intentionally has none.
  • Guarded branches come before the matching unguarded branch.
  • Comma-separated branches do not use guard conditions.
  • Closed-domain when expressions remain exhaustive without unnecessary else.
  • Open-domain fallbacks are still explicit.
  • Smart casts still work without as, !!, or duplicated casts.
  • The new shape is easier to scan than the old shape.

RED/GREEN agent scenarios

  1. Direct: a sealed result maps one data-class subtype and two singleton outcomes through else. RED recommends class names as value branches or drops the data payload. GREEN uses is for class subtypes, value matches for objects, and keeps the payload smart-cast where the mapping needs it.
  2. Novel: plain Kotlin navigation uses a one-shot Flow plus a sealed route renderer. GREEN combines concurrency guidance with this skill and makes data routes explicit; it does not infer a Compose state concern without Compose APIs or ownership evidence.
  3. Counterexample: an external integer status code has a deliberate unknown fallback. GREEN keeps else because the domain is open.
  4. No-change: an exhaustive when already uses each subtype payload without casts. GREEN reports no control-flow change.

When NOT to apply

  • Do not introduce guard conditions if the project Kotlin version does not support them.
  • Do not turn unrelated boolean checks into an awkward subject when.
  • Do not remove a deliberate else for open-world external input.
  • Do not flatten code if it makes cleanup, transaction boundaries, or error handling less obvious.

Related

Run your whole company from one repo you own.

Start with one job and grow from there.