irahardianto/agy-perf-optimization-demo/kotlin-idioms

Kotlin Idioms and Patterns

Kotlin rewards conciseness, null safety, and coroutine-based concurrency. Idiomatic Kotlin = safe, expressive, interop-aware.

Scope: Kotlin coding idioms. Test naming: .agents/rules/testing-strategy.md.

Null Safety

1. `?` for nullable types — never platform types without annotation:

``kotlin fun findById(id: String): Task? // explicitly nullable fun getById(id: String): Task // guaranteed non-null — throws if not found ``

1. Prefer `?.let {}` and `?:` (Elvis) over null checks.

1. Never `!!` in production — use requireNotNull with a message.

Data Classes and Sealed Types

1. `data class` for DTOs and domain objects:

``kotlin data class CreateTaskRequest(val title: String, val priority: Priority) ``

1. `sealed class`/`sealed interface` for restricted hierarchies:

``kotlin sealed interface TaskResult { data class Success(val task: Task) : TaskResult data class NotFound(val id: String) : TaskResult data class ValidationError(val errors: List<String>) : TaskResult } ``

1. Exhaustive `when` with sealed types:

``kotlin when (result) { is TaskResult.Success -> ok(result.task) is TaskResult.NotFound -> notFound(result.id) is TaskResult.ValidationError -> badRequest(result.errors) } ``

Coroutines

1. Structured concurrency — coroutineScope, supervisorScope.
2. Never `GlobalScope.launch` — always scoped.
3. `Flow` for reactive streams:

``kotlin fun observeTasks(): Flow<List<Task>> = flow { while (currentCoroutineContext().isActive) { emit(storage.getAll()) delay(5.seconds) } } ``

Naming

1. PascalCase for classes. camelCase for functions, properties.
2. No `get`/`set` prefixes — use properties.
3. Backtick function names only in tests: ` should create task when valid() `

Testing

1. kotest or JUnit 5 + MockK:

``kotlin @Test fun create task returns task when valid() { val result = service.create("Test", Priority.HIGH) assertThat(result.title).isEqualTo("Test") } ``

Formatting and Static Analysis

Related

• Code Idioms and Conventions .agents/rules/code-idioms-and-conventions.md
• Testing Strategy .agents/rules/testing-strategy.md
• Error Handling Principles .agents/rules/error-handling-principles.md