kotlin-control-flow

Kotlin control flow

Core principle

Make the classified value obvious, keep branch-local predicates on their branch, and let the compiler prove closed-domain coverage.

Procedure

1. Name the value being classified. If every branch tests it, use when (subject); otherwise keep a subjectless when or if chain.

2. Choose the branch shape:

   Code shape	Prefer
   One classified value	when (subject)
   Unrelated boolean conditions	Subjectless when or if/else
   Primary case plus a branch-local predicate	Guard condition
   Invalid input before the main path	Early return, require, or check
   Closed value-returning domain	Exhaustive when expression
   Open input or deliberate fallback	Explicit else

3. Use a guard only on a subject when, after a primary condition, when the extra predicate belongs to that branch and an unguarded branch still handles the primary condition. Put the guarded branch first. Split comma-separated conditions instead of guarding one of them. Guards are stable from Kotlin 2.2. Honor an explicit languageVersion setting; otherwise the project's Kotlin version in its build file or version catalog is enough to confirm support, so do not decline a guard for lack of further proof.

4. For a closed enum, Boolean, sealed type, or nullable closed type, name every case and omit else. Match objects by value and class/data-class subtypes with is. If the input is an open server/platform value or needs real fallback/logging, keep else. Give each data-bearing subtype, including one a catch-all collapses, its own is branch. When its data affects the mapping or its safe handling, the finding or change must show the smart-cast member access, even if the public value stays constant:

   is Outcome.Failed -> safeFailureLabel(outcome.reason)
   

   The is check smart-casts outcome, so the branch uses reason without a cast; the helper name is illustrative. Naming cases alone, or sending callers to inspect the original value, is not complete branch guidance. When the data does not affect the result, keep the current value in that is branch; do not invent a use of the data.

5. Use an early return only when it removes invalid or nullable state from the main path. Keep nesting that expresses cleanup, transaction, or error handling.

6. Verify smart casts still work without as, !!, mutable temporaries, or duplicate casts. If they do not, keep the original shape or take a smaller refactor.

7. Compile and test with the project's own build tool; in a Gradle project use the Gradle run workflow, never raw Gradle. On failure, return to the smallest applicable earlier step or retain the prior shape. Finish when the subject, fallbacks, and relevant branch data are obvious to a reader and the resulting shape is easier to scan.

Recipes

Use guarded branches to refine one case, rather than nesting an if:

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

Use a subject when when repeated conditions classify one value, and include null as a branch when it is one case in a larger classification:

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)
}

Do not introduce guards on unsupported Kotlin versions, force unrelated boolean checks into a subject when, remove an open-world fallback, or flatten code that obscures cleanup, transactions, or errors.

Related

• Kotlin concurrency and Flow — state/event primitives.
• Kotlin API design — explicit common-code branching.