Kotlin Style Guide

Style Categories

class UserService
val userName = "john"
fun calculateTotal()

if (condition) {
    doSomething()
}

/**
 * Calculates user age
 */
fun calculateAge(): Int

// Imports
// Class declaration
// Properties
// Functions

🔹 Naming Conventions

Use consistent naming patterns for different code elements:

// Classes and interfaces - PascalCase
class UserService
interface PaymentProcessor
data class OrderItem(val id: Long, val name: String)

// Functions and variables - camelCase
fun calculateTotalPrice(items: List<Item>): Double {
    val taxRate = 0.08
    var subtotal = 0.0
    
    for (item in items) {
        subtotal += item.price
    }
    
    return subtotal * (1 + taxRate)
}

// Constants - SCREAMING_SNAKE_CASE
const val MAX_RETRY_ATTEMPTS = 3
const val DEFAULT_TIMEOUT_SECONDS = 30

// Package names - lowercase with dots
package com.example.userservice.repository

// File names - PascalCase matching main class
// UserService.kt, PaymentProcessor.kt

// Boolean properties - use "is" prefix when appropriate
val isActive: Boolean = true
val hasPermission: Boolean = false
val canEdit: Boolean = user.role == Role.ADMIN

🔹 Code Formatting

Consistent formatting makes code easier to read:

// Indentation - 4 spaces (not tabs)
class OrderService(
    private val orderRepository: OrderRepository,
    private val paymentService: PaymentService,
    private val emailService: EmailService
) {
    
    // Function formatting
    fun processOrder(
        customerId: Long,
        items: List<OrderItem>,
        shippingAddress: Address
    ): Order {
        // Local variables
        val customer = customerService.findById(customerId)
            ?: throw CustomerNotFoundException("Customer $customerId not found")
        
        val order = Order(
            customerId = customerId,
            items = items,
            shippingAddress = shippingAddress,
            status = OrderStatus.PENDING
        )
        
        // Control flow formatting
        if (items.isEmpty()) {
            throw IllegalArgumentException("Order must contain at least one item")
        }
        
        // Chain calls formatting
        val totalPrice = items
            .filter { it.isAvailable }
            .map { it.price * it.quantity }
            .reduce { acc, price -> acc + price }
        
        // When expression formatting
        val shippingCost = when {
            totalPrice > 100.0 -> 0.0
            totalPrice > 50.0 -> 5.0
            else -> 10.0
        }
        
        return orderRepository.save(order)
    }
}

🔹 Documentation and Comments

Write clear documentation using KDoc and comments:

/**
 * Service for managing user accounts and authentication.
 * 
 * This service provides methods for user registration, login,
 * password management, and profile updates.
 * 
 * @property userRepository Repository for user data access
 * @property passwordEncoder Service for password encryption
 * @since 1.0.0
 */
class UserService(
    private val userRepository: UserRepository,
    private val passwordEncoder: PasswordEncoder
) {
    
    /**
     * Registers a new user account.
     * 
     * @param email User's email address (must be unique)
     * @param password Plain text password (will be encrypted)
     * @param fullName User's full name
     * @return The created user account
     * @throws UserAlreadyExistsException if email is already registered
     * @throws InvalidEmailException if email format is invalid
     */
    fun registerUser(
        email: String,
        password: String,
        fullName: String
    ): User {
        // Validate email format
        if (!isValidEmail(email)) {
            throw InvalidEmailException("Invalid email format: $email")
        }
        
        // Check if user already exists
        if (userRepository.existsByEmail(email)) {
            throw UserAlreadyExistsException("User with email $email already exists")
        }
        
        // Create and save user
        val encryptedPassword = passwordEncoder.encode(password)
        val user = User(
            email = email,
            password = encryptedPassword,
            fullName = fullName,
            createdAt = Instant.now()
        )
        
        return userRepository.save(user)
    }
    
    /**
     * Validates email format using regex pattern.
     * 
     * @param email Email to validate
     * @return true if email format is valid
     */
    private fun isValidEmail(email: String): Boolean {
        // Simple email validation - in production, use a proper library
        val emailRegex = "^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$"
        return email.matches(emailRegex.toRegex())
    }
}

🔹 File and Class Organization

Organize your code files and classes consistently:

// File: UserService.kt
package com.example.service

// 1. Imports - grouped and sorted
import com.example.model.User
import com.example.repository.UserRepository
import com.example.exception.UserNotFoundException
import java.time.Instant
import java.util.UUID

// 2. File-level documentation
/**
 * User management service implementation.
 */

// 3. Constants (if any)
private const val MAX_LOGIN_ATTEMPTS = 5

// 4. Main class
class UserService(
    private val userRepository: UserRepository
) {
    
    // 4a. Properties (grouped by visibility)
    private val loginAttempts = mutableMapOf<String, Int>()
    
    // 4b. Init blocks (if needed)
    init {
        // Initialization code
    }
    
    // 4c. Public functions
    fun findUserById(id: UUID): User? {
        return userRepository.findById(id)
    }
    
    fun createUser(email: String, name: String): User {
        val user = User(
            id = UUID.randomUUID(),
            email = email,
            name = name,
            createdAt = Instant.now()
        )
        return userRepository.save(user)
    }
    
    // 4d. Private functions
    private fun validateEmail(email: String): Boolean {
        return email.contains("@") && email.contains(".")
    }
    
    // 4e. Companion object (if needed)
    companion object {
        const val DEFAULT_PAGE_SIZE = 20
        
        fun createDefaultService(): UserService {
            return UserService(InMemoryUserRepository())
        }
    }
}

// 5. Extension functions (if any)
fun User.isActive(): Boolean = this.status == UserStatus.ACTIVE

// 6. Data classes and enums (if small and related)
enum class UserStatus {
    ACTIVE, INACTIVE, SUSPENDED
}

🔹 Best Practices Summary

Key principles for writing excellent Kotlin code: