Comments #

// This is a standalone single-line comment
val ageLimit = 18 // minimum age to create an account

val price = 50_000
val discount = 0.10
val finalPrice = price * (1 - discount) // result: 45000.0

// CORRECT: explaining the reasoning behind a magic number
val TIMEOUT_MS = 5_000 // internal network latency tolerance per SLA

// CORRECT: explaining a non-intuitive edge case
val lastIndex = list.size - 1 // size() returns 1-based, indexes are 0-based

// CORRECT: flagging a part that needs special attention
val hash = md5(password) // TODO: switch to bcrypt before production — see ticket SEC-204

// ANTI-PATTERN: comments that merely repeat the code
val name = "Budi" // set name to Budi
val age = 25      // set age to 25
println(name)     // print name

/*
    This algorithm uses a sliding window approach to compute
    a moving average with O(n) complexity, instead of O(n²)
    if using a nested loop. Reference: https://en.wikipedia.org/wiki/Sliding_window_protocol
*/
fun movingAverage(data: List<Double>, window: Int): List<Double> {
    if (data.size < window) return emptyList()
    
    val result = mutableListOf<Double>()
    var sum = data.take(window).sum()
    result.add(sum / window)
    
    for (i in window until data.size) {
        sum += data[i] - data[i - window]
        result.add(sum / window)
    }
    
    return result
}

/*
    This function handles three different scenarios:
    
    /* Scenario 1: empty data */
    If the list is empty, return emptyList() immediately
    
    /* Scenario 2: window larger than the data */
    Can't compute an average — return emptyList()
    
    /* Scenario 3: normal */
    Compute with a sliding window
*/
fun processData(data: List<Double>, window: Int): List<Double> {
    // implementation...
    return emptyList()
}

fun calculateTotal(items: List<Int>): Int {
    /*
    // Old implementation — too slow for large datasets
    var total = 0
    for (item in items) {
        total += item
    }
    return total
    */
    
    // New implementation with reduce
    return items.reduce { acc, item -> acc + item }
}

/**
 * Calculates compound interest based on initial principal, interest rate, and duration.
 *
 * Formula used: A = P(1 + r/n)^(nt)
 * where P is the initial principal, r is the annual interest rate (decimal),
 * n is the compounding frequency per year, and t is the duration in years.
 *
 * @param principal Initial principal in Rupiah
 * @param interestRate Annual interest rate as a decimal (e.g., 0.05 for 5%)
 * @param years Investment duration in years
 * @param frequency Compounding frequency per year (default: 12 for monthly)
 * @return Total investment value after the specified period
 */
fun compoundInterest(
    principal: Double,
    interestRate: Double,
    years: Int,
    frequency: Int = 12
): Double {
    return principal * Math.pow(1 + interestRate / frequency, (frequency * years).toDouble())
}

/**
 * Represents a user in the system.
 *
 * This class is a data class used as the main model
 * for user CRUD operations. Every user has a unique ID
 * generated at creation time that can't be changed.
 *
 * @property id Unique user ID — automatically generated by the database
 * @property name User's full name, at least 2 characters
 * @property email Verified email address, must be unique across the system
 * @property role User's role in the system, default [Role.USER]
 * @property active Account active status, false means the account is suspended
 *
 * @see UserRepository
 * @see Role
 * @since 1.0.0
 */
data class User(
    val id: Long,
    val name: String,
    val email: String,
    val role: Role = Role.USER,
    val active: Boolean = true
)

/**
 * Roles available in the authorization system.
 *
 * @property ADMIN Full access to all features and user management
 * @property MODERATOR Can manage content but can't modify other users
 * @property USER Standard access to features available to the public
 */
enum class Role {
    ADMIN, MODERATOR, USER
}

/**
 * Contract for all repositories that manage user data.
 *
 * Implementations of this interface must be thread-safe because they
 * can be called from coroutines running on different threads concurrently.
 *
 * @see User
 * @see UserRepositoryImpl
 */
interface UserRepository {
    
    /**
     * Finds a user by their ID.
     *
     * @param id The user ID to look up
     * @return A [User] object if found, null if it doesn't exist
     */
    suspend fun findById(id: Long): User?
    
    /**
     * Finds a user by their email address.
     *
     * The search is case-insensitive — "[email protected]" and
     * "[email protected]" are considered the same email.
     *
     * @param email The email address to look up
     * @return A [User] object if found, null if it doesn't exist
     */
    suspend fun findByEmail(email: String): User?
    
    /**
     * Saves a new user to the database.
     *
     * @param user The user data to save. The [User.id] field
     *             is ignored — the ID is generated by the database.
     * @return The [User] object complete with its newly generated ID
     * @throws IllegalArgumentException if the email is already registered
     * @throws IllegalArgumentException if the name is shorter than 2 characters
     */
    suspend fun save(user: User): User
    
    /**
     * Permanently deletes a user from the database.
     *
     * This operation can't be undone. All user-related data
     * (profile, transaction history, etc.) is also deleted because
     * of the foreign key constraint with CASCADE DELETE.
     *
     * @param id The user ID to delete
     * @return true if the user was successfully deleted, false if the ID wasn't found
     */
    suspend fun delete(id: Long): Boolean
}

/**
 * Validates password strength based on the following criteria:
 *
 * - At least **8 characters**
 * - Contains at least one **uppercase letter**
 * - Contains at least one **number**
 * - Contains at least one **special character** (`!@#$%^&*`)
 *
 * Usage example:
 * ```kotlin
 * val strong = validatePassword("P@ssw0rd!")  // true
 * val weak = validatePassword("password")  // false
 * ```
 *
 * > **Note:** This function only validates the format, it doesn't check
 * > whether the password has ever leaked in a credential leak database.
 *
 * @param password The password to validate
 * @return true if it meets all criteria, false if not
 * @see [HaveIBeenPwned](https://haveibeenpwned.com/API/v3) for credential leak checks
 */
fun validatePassword(password: String): Boolean {
    val uppercase = Regex("[A-Z]")
    val digit = Regex("[0-9]")
    val specialChar = Regex("[!@#\\$%^&*]")
    
    return password.length >= 8 &&
        uppercase.containsMatchIn(password) &&
        digit.containsMatchIn(password) &&
        specialChar.containsMatchIn(password)
}

/**
 * Sends a notification to all users with the [Role.ADMIN] role.
 *
 * This function calls [sendEmail] internally for each admin.
 * Make sure the SMTP configuration is correct in [EmailConfig] before
 * calling this function.
 *
 * @param message The notification content to send
 * @throws [EmailException] if the SMTP connection fails
 */
fun notifyAdmins(message: String) {
    // implementation...
}

plugins {
    kotlin("jvm") version "2.0.0"
    id("org.jetbrains.dokka") version "1.9.20"
}

./gradlew dokkaHtml

// ANTI-PATTERN: non-descriptive names, needs comments to explain
// Calculate d based on the business formula
fun calc(p: Double, r: Double, t: Int): Double {
    return p * Math.pow(1 + r, t.toDouble())
}

// CORRECT: descriptive names — no comments needed
fun calculateFinalInvestmentValue(initialCapital: Double, annualInterestRate: Double, years: Int): Double {
    return initialCapital * Math.pow(1 + annualInterestRate, years.toDouble())
}

// ANTI-PATTERN: explaining what's already obvious
val pageLimit = 20 // set page limit to 20

// CORRECT: explaining why this number was chosen
val pageLimit = 20 // calibrated based on median mobile user scroll time — see UX research Q3

// ANTI-PATTERN: explaining what's already visible from the code
// Loop from 0 to the length of the list
for (i in 0 until list.size) { ... }

// CORRECT: no comment needed at all if the code is already clear
for (item in list) { ... }

// ANTI-PATTERN: a long comment hiding complex code
// This function takes data from the cache if available,
// if not, takes it from the database, stores it in the cache,
// then returns the result, but if the database also errors,
// tries to fall back to a local file, and if everything fails returns null
fun fetchData(id: String): Data? {
    // ... 80 lines of complex code ...
}

// CORRECT: extract into small functions whose names speak for themselves
fun fetchData(id: String): Data? {
    return fetchFromCache(id)
        ?: fetchFromDatabaseAndCache(id)
        ?: fetchFromLocalFallback(id)
}

// TODO: add input validation before calling the external API
fun sendData(payload: String) { ... }

// FIXME: there's a race condition here when two threads call this simultaneously
fun updateCounter() { ... }

// HACK: workaround for a bug in the third-party library version 2.3.1
// Remove this after they release a fix in version 2.4.0
val result = library.processData(input.trim() + "\n")

// NOTE: this function deliberately doesn't use coroutines because
// it needs to block until finished — the caller context expects a synchronous value
fun fetchConfig(): Config { ... }

/*
 * Utilities for cryptographic operations used across the application.
 *
 * All functions in this file use algorithms that have been security-audited.
 * DO NOT add custom cryptography implementations — use what's already here.
 *
 * Author: Security Team
 * Last updated: 2024-03
 */

package com.myapp.util.crypto

import javax.crypto.Cipher
// ...

fun compressData(data: ByteArray): ByteArray {
    val output = ByteArrayOutputStream()
    
    // GZIPOutputStream must be flushed and closed explicitly
    // before taking the bytes from ByteArrayOutputStream.
    // Calling output.toByteArray() before gzip.close() produces
    // corrupted data — this is non-intuitive Java IO behavior.
    GZIPOutputStream(output).use { gzip ->
        gzip.write(data)
    }
    
    return output.toByteArray()
}

// Format: +62-XXX-XXXX-XXXX or 08XX-XXXX-XXXX
// Supports spaces, dashes, or no separator
val REGEX_ID_PHONE_NUMBER = Regex(
    """^(\+62|0)[0-9]{2,3}[-\\s]?[0-9]{3,4}[-\\s]?[0-9]{4}$"""
)

// Standard email format — doesn't support quoted strings or IP literals
// because our use case doesn't require them
val REGEX_EMAIL = Regex("""^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$""")