Jetpack Compose Rules

To ensure predictable UI and performance, follow these rules regarding how Composables emit content:

• Emit XOR Return: A Composable should either emit layout content OR return a value, but never both. If you need to provide control surfaces, use parameters.
• Emit a single layout node: A Composable should ideally emit zero or one layout node to remain cohesive. If a function emits multiple nodes (e.g., Text, Image, and Button directly), it becomes difficult to use in different parent layouts like Row or Box. Wrap them in a single layout (like Column) instead.
• Hoist single conditional layouts: If a layout's only purpose is to wrap a conditional child, move the condition outside the layout to avoid emitting an empty container.

Example: Hoisting conditions

// ❌ The Column exists only to wrap a conditional child.
@Composable
fun Content(showMessage: Boolean) {
    Column {
        if (showMessage) {
            Text("Hello")
        }
    }
}

// ✅ Hoist the condition so the layout is only emitted when it has content.
@Composable
fun Content(showMessage: Boolean) {
    if (showMessage) {
        Column {
            Text("Hello")
        }
    }
}

To keep composables readable and maintainable, avoid deep nesting of content emitters. If a function becomes too deeply nested, extract inner sections into private @Composable functions.

Configuration: The nesting threshold defaults to 3. You can tune this value using:

• Detekt: composableNestingDepthThreshold
• ktlint (.editorconfig): compose_composable_nesting_depth_threshold

Rule Identifiers:

• ktlint: compose:composable-nesting-depth-check
• detekt: ComposableNestingDepth

// ❌ Too deeply nested
@Composable
fun Foo() {
    Box {
        Box {
            Box {
                Box {
                    Box {
                        Text("hello")
                    }
                }
            }
        }
    }
}

// ✅ Better: Inner sections extracted to a private composable
@Composable
fun Foo() {
    Box {
        Box {
            Box {
                Bar()
            }
        }
    }
}

@Composable
private fun Bar() {
    Box {
        Box {
            Text("hello")
        }
    }
}

The functional tests use Gradle TestKit to simulate a real development environment. The process follows these steps:

1. Project Creation: A temporary directory is created with a complete Gradle project structure (including build.gradle.kts and source files).
2. Execution: Gradle commands are run via GradleRunner (e.g., spotlessKotlinCheck or detekt).
3. Assertion: The tests assert on task outcomes (SUCCESS, FAILED, UP_TO_DATE) and inspect build output content to ensure rules are correctly detecting violations.

Example Test Pattern:

@Test
fun `ModifierMissing is detected via ktlint`() {
    setupKtlintProject()

    projectDir.writeFile(
        "src/main/kotlin/Violations.kt",
        """
        @Composable
        fun MissingModifier() {
            Row { }  // Missing modifier parameter
        }
        """
    )

    val result = createGradleRunner(
        projectDir = projectDir,
        arguments = listOf("spotlessKotlinCheck")
    ).buildAndFail()

    result.assertOutputContains("compose:modifier-missing-check")
}

Standard Kotlin collection interfaces (List<T>, Map<T>, Set<T>) are considered unstable by the Compose compiler because they cannot guarantee immutability. To ensure stability and prevent unnecessary recompositions, use one of the following approaches:

1. Use Kotlinx Immutable Collections (Preferred): Use types like ImmutableList<T> with persistentListOf().
2. Wrap in a stable class: Wrap a standard collection in a data class annotated with @Immutable.
3. Stability Configuration: Alternatively, add kotlin.collections.* to your project's stability configuration to treat them as stable.

Rule Identifiers:

• ktlint: compose:unstable-collections
• detekt: UnstableCollections

// ❌ Unstable: The compiler cannot guarantee immutability
val list: List<String> = mutableListOf()

// ✅ Stable: Using Kotlinx Immutable Collections
val list: ImmutableList<String> = persistentListOf<String>()

// ✅ Stable: Wrapping in an @Immutable class
@Immutable
data class StringList(val items: List<String>)
val list: StringList = StringList(yourList)

To maintain unidirectional data flow and ensure recomposition works correctly, avoid passing mutable objects or state holders as parameters to @Composable functions.

• Do not use inherently mutable types: Avoid passing types like ArrayList<T> or ViewModel directly. Mutations to these objects often fail to trigger recomposition. Instead, pass immutable values and use lambda callbacks for mutations.
• Do not use MutableState<T>: Passing MutableState splits state ownership. Instead, make the component stateless by passing the raw value and an event callback.
• Do not use State<T>: Passing State holders makes components harder to test. Pass the snapshot value and a callback instead.

Example: Correct State Pattern

// ❌ Passing State down
@Composable
fun Counter(label: String, count: State<Int>) { /* ... */ }

// ✅ Pass values and events instead
@Composable
fun Counter(label: String, count: Int, onCountChange: (Int) -> Unit) { /* ... */ }