Komentar #

// Ini adalah komentar satu baris yang berdiri sendiri
val batasUmur = 18 // batas minimal untuk membuat akun

val harga = 50_000
val diskon = 0.10
val hargaAkhir = harga * (1 - diskon) // hasil: 45000.0

// BENAR: menjelaskan alasan di balik magic number
val TIMEOUT_MS = 5_000 // batas toleransi latensi jaringan internal per SLA

// BENAR: menjelaskan edge case yang tidak intuitif
val indeksAkhir = daftar.size - 1 // size() mengembalikan 1-based, indeks adalah 0-based

// BENAR: menandai bagian yang perlu perhatian khusus
val hash = md5(password) // TODO: ganti ke bcrypt sebelum production — lihat tiket SEC-204

// ANTI-PATTERN: komentar yang hanya mengulang kode
val nama = "Budi" // set nama ke Budi
val umur = 25     // set umur ke 25
println(nama)     // cetak nama

/*
    Algoritma ini menggunakan pendekatan sliding window untuk menghitung
    rata-rata bergerak dengan kompleksitas O(n), alih-alih O(n²) jika
    menggunakan nested loop. Referensi: https://en.wikipedia.org/wiki/Sliding_window_protocol
*/
fun rataRataBergerak(data: List<Double>, window: Int): List<Double> {
    if (data.size < window) return emptyList()
    
    val hasil = mutableListOf<Double>()
    var jumlah = data.take(window).sum()
    hasil.add(jumlah / window)
    
    for (i in window until data.size) {
        jumlah += data[i] - data[i - window]
        hasil.add(jumlah / window)
    }
    
    return hasil
}

/*
    Fungsi ini menangani tiga skenario berbeda:
    
    /* Skenario 1: data kosong */
    Jika list kosong, kembalikan emptyList() langsung
    
    /* Skenario 2: window lebih besar dari data */
    Tidak bisa menghitung rata-rata — kembalikan emptyList()
    
    /* Skenario 3: normal */
    Hitung dengan sliding window
*/
fun prosesData(data: List<Double>, window: Int): List<Double> {
    // implementasi...
    return emptyList()
}

fun hitungTotal(items: List<Int>): Int {
    /*
    // Implementasi lama — terlalu lambat untuk dataset besar
    var total = 0
    for (item in items) {
        total += item
    }
    return total
    */
    
    // Implementasi baru dengan reduce
    return items.reduce { acc, item -> acc + item }
}

/**
 * Menghitung bunga majemuk berdasarkan modal awal, suku bunga, dan durasi.
 *
 * Formula yang digunakan: A = P(1 + r/n)^(nt)
 * di mana P adalah modal awal, r adalah suku bunga tahunan (desimal),
 * n adalah frekuensi penggandaan per tahun, dan t adalah durasi dalam tahun.
 *
 * @param modal Modal awal dalam Rupiah
 * @param sukuBunga Suku bunga tahunan dalam bentuk desimal (contoh: 0.05 untuk 5%)
 * @param tahun Durasi investasi dalam tahun
 * @param frekuensi Frekuensi penggandaan per tahun (default: 12 untuk bulanan)
 * @return Total nilai investasi setelah periode yang ditentukan
 */
fun bungaMajemuk(
    modal: Double,
    sukuBunga: Double,
    tahun: Int,
    frekuensi: Int = 12
): Double {
    return modal * Math.pow(1 + sukuBunga / frekuensi, (frekuensi * tahun).toDouble())
}

/**
 * Representasi seorang pengguna dalam sistem.
 *
 * Kelas ini adalah data class yang digunakan sebagai model utama
 * untuk operasi CRUD pengguna. Setiap pengguna memiliki ID unik
 * yang di-generate saat pembuatan dan tidak bisa diubah.
 *
 * @property id ID unik pengguna — di-generate otomatis oleh database
 * @property nama Nama lengkap pengguna, minimal 2 karakter
 * @property email Alamat email terverifikasi, harus unik di seluruh sistem
 * @property peran Peran pengguna dalam sistem, default [Peran.PENGGUNA]
 * @property aktif Status aktif akun, false berarti akun di-suspend
 *
 * @see PenggunaRepository
 * @see Peran
 * @since 1.0.0
 */
data class Pengguna(
    val id: Long,
    val nama: String,
    val email: String,
    val peran: Peran = Peran.PENGGUNA,
    val aktif: Boolean = true
)

/**
 * Peran yang tersedia dalam sistem otorisasi.
 *
 * @property ADMIN Akses penuh ke seluruh fitur dan manajemen pengguna
 * @property MODERATOR Bisa mengelola konten tapi tidak bisa mengubah pengguna lain
 * @property PENGGUNA Akses standar ke fitur yang tersedia untuk publik
 */
enum class Peran {
    ADMIN, MODERATOR, PENGGUNA
}

/**
 * Kontrak untuk semua repository yang mengelola data pengguna.
 *
 * Implementasi interface ini harus thread-safe karena bisa dipanggil
 * dari coroutine yang berjalan di thread berbeda secara bersamaan.
 *
 * @see Pengguna
 * @see PenggunaRepositoryImpl
 */
interface PenggunaRepository {
    
    /**
     * Mencari pengguna berdasarkan ID-nya.
     *
     * @param id ID pengguna yang dicari
     * @return Objek [Pengguna] jika ditemukan, null jika tidak ada
     */
    suspend fun cariById(id: Long): Pengguna?
    
    /**
     * Mencari pengguna berdasarkan alamat email.
     *
     * Pencarian bersifat case-insensitive — "[email protected]" dan
     * "[email protected]" dianggap email yang sama.
     *
     * @param email Alamat email yang dicari
     * @return Objek [Pengguna] jika ditemukan, null jika tidak ada
     */
    suspend fun cariByEmail(email: String): Pengguna?
    
    /**
     * Menyimpan pengguna baru ke dalam database.
     *
     * @param pengguna Data pengguna yang akan disimpan. Field [Pengguna.id]
     *                 akan diabaikan — ID di-generate oleh database.
     * @return Objek [Pengguna] lengkap dengan ID yang baru di-generate
     * @throws IllegalArgumentException jika email sudah terdaftar
     * @throws IllegalArgumentException jika nama lebih pendek dari 2 karakter
     */
    suspend fun simpan(pengguna: Pengguna): Pengguna
    
    /**
     * Menghapus pengguna secara permanen dari database.
     *
     * Operasi ini tidak bisa di-undo. Semua data terkait pengguna
     * (profil, riwayat transaksi, dll) ikut terhapus karena foreign key
     * constraint dengan CASCADE DELETE.
     *
     * @param id ID pengguna yang akan dihapus
     * @return true jika pengguna berhasil dihapus, false jika ID tidak ditemukan
     */
    suspend fun hapus(id: Long): Boolean
}

/**
 * Memvalidasi kekuatan password berdasarkan kriteria berikut:
 *
 * - Minimal **8 karakter**
 * - Mengandung minimal satu **huruf besar**
 * - Mengandung minimal satu **angka**
 * - Mengandung minimal satu **karakter spesial** (`!@#$%^&*`)
 *
 * Contoh penggunaan:
 * ```kotlin
 * val kuat = validasiPassword("P@ssw0rd!")  // true
 * val lemah = validasiPassword("password")  // false
 * ```
 *
 * > **Catatan:** Fungsi ini hanya memvalidasi format, bukan memeriksa
 * > apakah password pernah bocor di database credential leak.
 *
 * @param password Password yang akan divalidasi
 * @return true jika memenuhi semua kriteria, false jika tidak
 * @see [HaveIBeenPwned](https://haveibeenpwned.com/API/v3) untuk cek credential leak
 */
fun validasiPassword(password: String): Boolean {
    val hurufBesar = Regex("[A-Z]")
    val angka = Regex("[0-9]")
    val karakterSpesial = Regex("[!@#\$%^&*]")
    
    return password.length >= 8 &&
        hurufBesar.containsMatchIn(password) &&
        angka.containsMatchIn(password) &&
        karakterSpesial.containsMatchIn(password)
}

/**
 * Mengirim notifikasi ke semua pengguna dengan peran [Peran.ADMIN].
 *
 * Fungsi ini memanggil [kirimEmail] secara internal untuk setiap admin.
 * Pastikan konfigurasi SMTP sudah benar di [KonfigurasiEmail] sebelum
 * memanggil fungsi ini.
 *
 * @param pesan Isi notifikasi yang akan dikirim
 * @throws [EmailException] jika koneksi SMTP gagal
 */
fun notifikasiAdmin(pesan: String) {
    // implementasi...
}

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

./gradlew dokkaHtml

// ANTI-PATTERN: nama tidak deskriptif, butuh komentar untuk menjelaskan
// Hitung d berdasarkan formula bisnis
fun calc(p: Double, r: Double, t: Int): Double {
    return p * Math.pow(1 + r, t.toDouble())
}

// BENAR: nama yang deskriptif — komentar tidak diperlukan
fun hitungNilaiAkhirInvestasi(modalAwal: Double, sukuBungaTahunan: Double, tahun: Int): Double {
    return modalAwal * Math.pow(1 + sukuBungaTahunan, tahun.toDouble())
}

// ANTI-PATTERN: menjelaskan apa yang sudah jelas
val batasHalaman = 20 // set batas halaman ke 20

// BENAR: menjelaskan mengapa angka ini dipilih
val batasHalaman = 20 // dikalibrasi berdasarkan median waktu scroll pengguna mobile — lihat riset UX Q3

// ANTI-PATTERN: menjelaskan yang sudah terlihat dari kode
// Loop dari 0 sampai panjang list
for (i in 0 until daftar.size) { ... }

// BENAR: tidak perlu komentar sama sekali jika kodenya sudah jelas
for (item in daftar) { ... }

// ANTI-PATTERN: komentar panjang menutupi kode yang kompleks
// Fungsi ini mengambil data dari cache jika ada,
// kalau tidak ada ambil dari database, simpan ke cache,
// kemudian kembalikan hasilnya, tapi kalau database juga error,
// coba fallback ke file lokal, kalau semua gagal return null
fun ambilData(id: String): Data? {
    // ... 80 baris kode kompleks ...
}

// BENAR: ekstrak ke fungsi-fungsi kecil yang namanya berbicara sendiri
fun ambilData(id: String): Data? {
    return ambilDariCache(id)
        ?: ambilDariDatabaseDanCache(id)
        ?: ambilDariFallbackLokal(id)
}

// TODO: tambahkan validasi input sebelum memanggil API eksternal
fun kirimData(payload: String) { ... }

// FIXME: ada race condition di sini ketika dua thread memanggil ini bersamaan
fun updateKonter() { ... }

// HACK: workaround untuk bug di library pihak ketiga versi 2.3.1
// Hapus ini setelah mereka release fix di versi 2.4.0
val hasil = library.prosesData(input.trim() + "\n")

// NOTE: fungsi ini sengaja tidak menggunakan coroutine karena
// perlu diblok sampai selesai — konteks pemanggil mengharapkan nilai sinkron
fun ambilKonfigurasi(): Config { ... }

/*
 * Utilitas untuk operasi kriptografi yang digunakan di seluruh aplikasi.
 *
 * Semua fungsi di file ini menggunakan algoritma yang sudah diaudit keamanannya.
 * JANGAN menambahkan implementasi kriptografi kustom — gunakan yang sudah ada di sini.
 *
 * Penulis: Tim Security
 * Terakhir diperbarui: 2024-03
 */

package com.myapp.util.crypto

import javax.crypto.Cipher
// ...

fun kompresiData(data: ByteArray): ByteArray {
    val output = ByteArrayOutputStream()
    
    // GZIPOutputStream harus di-flush dan close secara eksplisit
    // sebelum mengambil bytes dari ByteArrayOutputStream.
    // Memanggil output.toByteArray() sebelum gzip.close() menghasilkan
    // data yang corrupt — ini perilaku yang tidak intuitif dari Java IO.
    GZIPOutputStream(output).use { gzip ->
        gzip.write(data)
    }
    
    return output.toByteArray()
}

// Format: +62-XXX-XXXX-XXXX atau 08XX-XXXX-XXXX
// Mendukung spasi, dash, atau tanpa pemisah
val REGEX_NOMOR_TELEPON_ID = Regex(
    """^(\+62|0)[0-9]{2,3}[-\s]?[0-9]{3,4}[-\s]?[0-9]{4}$"""
)

// Format email standar — tidak mendukung quoted string atau IP literal
// karena use case kami tidak memerlukannya
val REGEX_EMAIL = Regex("""^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$""")