ar4mirez/kotlin-guide

Kotlin Guide

Applies to: Kotlin 1.9+, JVM 17+, Coroutines, Android, Server-side

Core Principles

1. Null Safety: Leverage the type system to eliminate null pointer exceptions at compile time
2. Conciseness: Use data classes, scope functions, and destructuring to reduce boilerplate
3. Coroutines for Concurrency: Structured concurrency with coroutines, not raw threads
4. Immutability by Default: Prefer val over var, immutable collections over mutable
5. Interop Awareness: Write Kotlin-idiomatic code while maintaining clean Java interop boundaries

Guardrails

Version & Dependencies

• Use Kotlin 1.9+ with Gradle Kotlin DSL (build.gradle.kts)
• Target JVM 17+ for server-side, match Android minSdk for mobile
• Pin Kotlin and kotlinx library versions together (BOM alignment)
• Run ./gradlew dependencies to audit transitive dependencies

Code Style

• Run ktlint before every commit (format + check)
• Run detekt for static analysis (complexity, code smells)
• Packages: lowercase, no underscores (com.example.userservice)
• Classes: PascalCase | Functions/properties: camelCase | Constants: SCREAMING_SNAKE_CASE
• Follow Kotlin Coding Conventions

Null Safety

• Never use !! (not-null assertion) in production code
• Use safe calls (?.), elvis (?:), and smart casts instead
• Nullable types only at API boundaries (deserialization, Java interop)
• Prefer requireNotNull() or checkNotNull() with meaningful messages over !!
• Use ?.let { } for nullable transformations, not nested if checks

// BAD: crashes at runtime
val length = name!!.length

// GOOD: safe call with fallback
val length = name?.length ?: 0

// GOOD: explicit contract with clear error
val validName = requireNotNull(name) { "User name must not be null for ID=$id" }

Coroutines

• Always use structured concurrency (coroutineScope, supervisorScope)
• Never use GlobalScope in production code
• Use withContext(Dispatchers.IO) for blocking I/O operations
• Always handle CancellationException correctly (rethrow, never swallow)
• Set timeouts with withTimeout or withTimeoutOrNull for external calls

// BAD: unstructured, leaks coroutines
GlobalScope.launch { fetchData() }

// GOOD: structured concurrency, respects parent lifecycle
coroutineScope {
    val user = async { userService.getUser(id) }
    val orders = async { orderService.getOrders(id) }
    UserWithOrders(user.await(), orders.await())
}

Extension Functions

• Use extension functions to add behavior, not to bypass access control
• Keep extensions in a dedicated file (StringExtensions.kt, DateExtensions.kt)
• Do not add extensions to Any or overly generic types
• Prefer member functions for core behavior, extensions for utility/convenience
• Document extensions with @receiver KDoc tag when purpose is not obvious

Project Structure

myproject/
├── app/                          # Application module or main entry
│   └── src/main/kotlin/
├── domain/                       # Business logic, entities, use cases
│   └── src/main/kotlin/
│       └── com/example/domain/
│           ├── model/            # Data classes, sealed classes
│           ├── repository/       # Repository interfaces
│           └── usecase/          # Business operations
├── data/                         # Data layer implementations
│   └── src/main/kotlin/
│       └── com/example/data/
│           ├── repository/       # Repository implementations
│           ├── remote/           # API clients, DTOs
│           └── local/            # Database, DAOs
├── presentation/                 # UI or API controllers
├── build.gradle.kts
├── settings.gradle.kts
└── gradle.properties

• domain/ has zero framework dependencies (pure Kotlin)
• data/ depends on domain/, implements repository interfaces
• presentation/ depends on domain/, never imports from data/ directly
• No circular module dependencies

Key Patterns

Data Classes & Value Classes

data class User(
    val id: UserId,
    val email: Email,
    val name: String,
    val role: Role = Role.VIEWER,
) {
    init {
        require(name.isNotBlank()) { "User name must not be blank" }
    }
}

// Value classes for type-safe IDs (zero runtime overhead)
@JvmInline
value class UserId(val value: String) {
    init { require(value.isNotBlank()) { "UserId must not be blank" } }
}

Sealed Classes & Interfaces

sealed interface Result<out T> {
    data class Success<T>(val data: T) : Result<T>
    data class Failure(val error: AppError) : Result<Nothing>
}

sealed class AppError(val message: String) {
    data class NotFound(val resource: String, val id: String) :
        AppError("$resource with ID $id not found")
    data class Validation(val field: String, val reason: String) :
        AppError("Validation failed for $field: $reason")
    data class Unauthorized(val detail: String = "Authentication required") :
        AppError(detail)
}

// Exhaustive when expressions
fun <T> Result<T>.getOrThrow(): T = when (this) {
    is Result.Success -> data
    is Result.Failure -> throw error.toException()
}

Scope Functions Quick Reference

| Function | Context | Returns | Use for | |----------|---------|---------|---------| | let | it | Lambda result | Nullable transforms, scoped vars | | run | this | Lambda result | Compute value using object context | | with | this | Lambda result | Operate on non-null object | | apply | this | Object itself | Configure/build an object | | also | it | Object itself | Side effects (logging, events) |

// apply: configure and return the object
val request = HttpRequest.Builder().apply {
    url(endpoint)
    header("Authorization", "Bearer $token")
    timeout(Duration.ofSeconds(30))
}.build()

// also: side effects without modifying the chain
val savedUser = userRepository.save(newUser).also { user ->
    logger.info("Created user: ${user.id}")
}

Testing

Standards

• Test files: *Test.kt in src/test/kotlin/ (mirror source package)
• Use JUnit 5 with @Test, @Nested, @DisplayName
• Use MockK for mocking (idiomatic Kotlin, supports coroutines)
• Table-driven style with @ParameterizedTest and @MethodSource
• Coverage target: >80% for business logic, >60% overall
• Use runTest from kotlinx-coroutines-test for coroutine tests

Unit Test Pattern

class UserServiceTest {
    private val userRepository = mockk<UserRepository>()
    private val eventBus = mockk<EventBus>(relaxed = true)
    private val service = UserService(userRepository, eventBus)

    @Nested
    @DisplayName("createUser")
    inner class CreateUser {
        @Test
        fun `creates user with valid input`() = runTest {
            coEvery { userRepository.save(any()) } returns mockUser
            val result = service.createUser(validInput)

            assertThat(result).isInstanceOf(Result.Success::class.java)
            coVerify { userRepository.save(any()) }
            coVerify { eventBus.publish(any<UserCreatedEvent>()) }
        }

        @Test
        fun `fails with blank name`() = runTest {
            val result = service.createUser(blankNameInput)

            assertThat(result).isInstanceOf(Result.Failure::class.java)
            coVerify(exactly = 0) { userRepository.save(any()) }
        }
    }
}

Parameterized Tests

companion object {
    @JvmStatic
    fun emailCases() = listOf(
        Arguments.of("[email protected]", true),
        Arguments.of("invalid-email", false),
        Arguments.of("", false),
    )
}

@ParameterizedTest(name = "email \"{0}\" valid={1}")
@MethodSource("emailCases")
fun `validates email format`(email: String, expected: Boolean) {
    val result = runCatching { Email(email) }
    assertThat(result.isSuccess).isEqualTo(expected)
}

Tooling

Essential Commands

./gradlew build                    # Compile + test + check
./gradlew test                     # Run all tests
./gradlew test --tests "*.UserServiceTest"  # Specific test class
./gradlew koverReport              # Coverage report
./gradlew ktlintCheck              # Check formatting
./gradlew ktlintFormat             # Auto-fix formatting
./gradlew detekt                   # Static analysis
./gradlew dependencies             # Dependency tree

Gradle Kotlin DSL Configuration

// build.gradle.kts
plugins {
    kotlin("jvm") version "1.9.22"
    id("org.jlleitschuh.gradle.ktlint") version "12.1.0"
    id("io.gitlab.arturbosch.detekt") version "1.23.4"
    id("org.jetbrains.kotlinx.kover") version "0.7.5"
}

kotlin { jvmToolchain(17) }

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.2")
    testImplementation(kotlin("test"))
    testImplementation("io.mockk:mockk:1.13.9")
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0")
    testImplementation("org.assertj:assertj-core:3.25.1")
}

detekt {
    config.setFrom("detekt.yml")
    buildUponDefaultConfig = true
}

kover {
    verify { rule { minBound(80) } }
}

Detekt Configuration

# detekt.yml
complexity:
  LongMethod:
    threshold: 50
  CyclomaticComplexMethod:
    threshold: 10
  LargeClass:
    threshold: 300
  LongParameterList:
    functionThreshold: 5
    constructorThreshold: 8
style:
  ForbiddenComment:
    values:
      - "TODO(?!\\(#\\d+\\))" # TODOs require issue reference
  MagicNumber:
    ignoreNumbers: ["-1", "0", "1", "2"]
  MaxLineLength:
    maxLineLength: 120
potential-bugs:
  UnsafeCast:
    active: true

References

For detailed patterns and examples, see:

• references/patterns.md -- Coroutine patterns, sealed class hierarchies, DSL builders, Flow patterns

External References

• Kotlin Coding Conventions
• Kotlin Coroutines Guide
• MockK Documentation
• ktlint
• detekt
• Kover Coverage
• Arrow (Functional Kotlin)