Kotlin Rules

Kotlin Rules

These rules come from app/rules/kotlin/ in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Kotlin. Apply them when writing or reviewing Kotlin code.

Kotlin Coding Style

Naming

• PascalCase: classes, interfaces, objects, type aliases, enum entries.
• camelCase: functions, properties, local variables, parameters.
• UPPER_SNAKE: compile-time constants (const val), top-level val constants.
• Backing properties: prefix with _ (private val _items, val items: List<T>).
• Package names: lowercase, no underscores (com.company.project.feature).

Null Safety

• Use nullable types only when nullability is semantically meaningful.
• Prefer ?.let { }, ?: (Elvis), and safe calls over !!.
• Never use !! except in tests or when null is truly impossible.
• Use requireNotNull() and require() for preconditions at public API boundaries.
• Use checkNotNull() and check() for state assertions.

Data Classes

• Use data class for DTOs, value objects, and state containers.
• Use copy() for immutable updates. Avoid mutable var in data classes.
• Use sealed class / sealed interface for restricted hierarchies.
• Use value class (inline class) for type-safe wrappers with zero overhead.
• Use object for singletons and namespace-like utility groupings.

Functions

• Use expression body (= expr) for single-expression functions.
• Use named arguments for functions with >2 parameters of the same type.
• Use default parameter values instead of overloaded functions.
• Use extension functions to add behavior without inheritance.
• Use suspend functions for async operations, not callbacks.

Collections

• Prefer listOf, mapOf, setOf (immutable) over mutableListOf.
• Use collection operators: map, filter, groupBy, associate.
• Use sequence {} for lazy evaluation on large collections.
• Prefer firstOrNull() over first() for safe access.
• Use destructuring: val (name, age) = user.

Scope Functions

• let: null-safe chaining and local scoping.
• apply: configure object after creation.
• also: side effects (logging, validation) in chains.
• run: compute a result using receiver's context.
• with: multiple operations on an object without chaining.
• Avoid nesting scope functions more than 1 level deep.

Formatting

• Use ktlint or detekt for automated formatting and linting.
• Use trailing commas in multi-line parameter/argument lists.
• Max line length: 120 characters (Kotlin convention).
• Use when expression over if-else chains for 3+ branches.

Kotlin Frameworks

Ktor (Server)

• Use routing DSL: routing { get("/users") { call.respond(users) } }.
• Use install() for plugins: ContentNegotiation, Authentication, CORS.
• Use call.receive<T>() for typed request body parsing with kotlinx.serialization.
• Use StatusPages plugin for centralized error handling.
• Use Routing with nested route("/api/v1") { } blocks for URL grouping.

Ktor (Client)

• Use HttpClient with engine configuration (CIO, OkHttp, Apache).
• Use install(ContentNegotiation) { json() } for JSON serialization.
• Use client.get<T>() with reified type for typed responses.
• Use HttpTimeout plugin for connection and request timeouts.
• Close HttpClient when done or use DI lifecycle management.

Spring Boot (Kotlin)

• Use constructor injection (Kotlin classes are final by default).
• Apply kotlin-spring plugin for open classes (required for proxying).
• Use @ConfigurationProperties with data classes for typed config.
• Use WebFlux with coroutines: coRouter { } and suspend handler functions.
• Use spring-boot-starter-validation with @Valid on Kotlin data classes.

Exposed (ORM)

• Use DSL API for type-safe queries: Users.select { Users.name eq "Ada" }.
• Use DAO API for Active Record-style: User.find { Users.age greaterEq 18 }.
• Wrap database operations in transaction { } blocks.
• Use SchemaUtils.create(Users) for schema management in development.

kotlinx.serialization

• Use @Serializable annotation on data classes for compile-time serialization.
• Use @SerialName("field_name") for JSON field name mapping.
• Use Json { ignoreUnknownKeys = true } for lenient deserialization.
• Use polymorphic serialization with sealed class and @Polymorphic.
• Prefer kotlinx.serialization over Jackson for pure Kotlin projects.

Koin (DI)

• Define modules: module { single { UserService(get()) } }.
• Use by inject<T>() for lazy injection in Android/Ktor.
• Use factory { } for new instance per injection, single { } for singleton.
• Use checkModules() in tests to verify DI graph completeness.

Compose (Multiplatform UI)

• Use @Composable functions for UI components. Keep them stateless.
• Use remember { } and mutableStateOf() for local state.
• Hoist state to callers: pass state down, events up.
• Use LaunchedEffect for side effects tied to composition lifecycle.
• Use ViewModel with StateFlow for screen-level state management.

Kotlin Patterns

Error Handling

• Use Result<T> for operations that can fail without exceptions.
• Use runCatching { } to wrap exception-throwing code into Result.
• Use sealed class hierarchies for domain errors: sealed class AppError.
• Prefer fold(), getOrElse(), getOrNull() over getOrThrow().
• Use require() / check() for preconditions; they throw IllegalArgumentException / IllegalStateException.

Coroutines

• Use suspend functions for sequential async operations.
• Use coroutineScope { } for structured concurrency with parallel work.
• Use async { } + await() for concurrent independent operations.
• Use supervisorScope { } when child failures should not cancel siblings.
• Use withContext(Dispatchers.IO) for blocking I/O in coroutine context.
• Use flow { } for cold asynchronous streams. Collect in lifecycle-aware scope.

Flow Patterns

• Use stateIn() and shareIn() to convert cold flows to hot shared state.
• Use combine() to merge multiple flows into derived state.
• Use flatMapLatest for search-as-you-type patterns (cancel previous).
• Use catch { } operator for upstream error handling in flows.
• Use flowOn(Dispatchers.IO) to shift upstream execution context.

Sealed Hierarchies

• Use sealed interface over sealed class when no shared state is needed.
• Use when expressions exhaustively on sealed types (compiler-enforced).
• Combine sealed types with data classes for typed state machines.
• Use sealed hierarchies for API responses: Success<T>, Error, Loading.

Delegation

• Use by lazy { } for thread-safe lazy initialization.
• Use by map for delegated properties backed by a Map.
• Use class delegation (class Foo : Bar by impl) to favor composition.
• Use observable / vetoable delegates for reactive property changes.

Builder Patterns

• Use DSL-style builders with @DslMarker annotation to prevent scope leakage.
• Use trailing lambda syntax for configuration blocks.
• Use apply { } for inline object configuration without a dedicated builder.
• Use buildList { }, buildMap { }, buildString { } for collection construction.

Anti-Patterns

• Overusing !!: masks null-safety guarantees. Use safe calls or require.
• Nesting scope functions: foo.let { it.also { ... }.run { } } -- flatten logic.
• Blocking the main thread: use withContext(Dispatchers.IO) for I/O.
• Using GlobalScope.launch: leaks coroutines. Use structured concurrency.
• Mutable shared state without synchronization: use Mutex or StateFlow.