Code Comments — Clean Code

Komentar yang baik menjelaskan mengapa, bukan apa. Jika kamu perlu komentar untuk menjelaskan apa yang kode lakukan, pertimbangkan untuk memperbaiki kodenya aga

Komentar yang baik menjelaskan mengapa, bukan apa. Jika kamu perlu komentar untuk menjelaskan apa yang kode lakukan, pertimbangkan untuk memperbaiki kodenya agar self-explanatory.

Komentar yang BURUK — menjelaskan yang sudah jelas:

// BURUK: komentar redundan
let count = 0; // inisialisasi count ke 0
count++; // increment count
const users = getUsers(); // ambil users
if (users.length > 0) { // kalau ada users
  processUsers(users); // proses users
}
// Semua komentar ini tidak menambah informasi apapun!

Komentar yang BAIK — menjelaskan mengapa:

// BAIK: menjelaskan keputusan bisnis
// Diskon 10% untuk pelanggan yang sudah belanja > 3 bulan
// berdasarkan keputusan meeting marketing 2024-03-15
if (customerAge > 90) {
  applyDiscount(0.1);
}

// BAIK: menjelaskan workaround
// Safari iOS memiliki bug dimana 100vh termasuk address bar.
// Gunakan window.innerHeight sebagai workaround.
// Ref: https://bugs.webkit.org/show_bug.cgi?id=141832
const viewportHeight = window.innerHeight;

// BAIK: menjelaskan regex yang kompleks
// Format nomor HP Indonesia: 08xx-xxxx-xxxx atau +628xx-xxxx-xxxx
const phoneRegex = /^(\+62|0)8[1-9]\d{7,10}$/;

Komentar yang BURUK — menyembunyikan kode buruk:

// BURUK: komentar sebagai pengganti nama yang baik
const d = 86400000; // jumlah milidetik dalam sehari

// BERSIH: nama yang menjelaskan diri sendiri
const MILLISECONDS_PER_DAY = 86400000;

// BURUK: komentar karena fungsi tidak jelas
// Mengambil user aktif yang login dalam 30 hari terakhir
// dan punya minimal 1 order yang sudah selesai
function getData() { ... }

// BERSIH: nama fungsi yang deskriptif
function getActiveUsersWithCompletedOrders() { ... }

Jenis komentar yang berguna:

// 1. TODO — pekerjaan yang belum selesai
// TODO: Tambahkan rate limiting setelah launch
// TODO(budi): Refactor setelah API v2 ready

// 2. HACK/FIXME — solusi sementara yang perlu diperbaiki
// HACK: setTimeout 0 karena DOM belum ready saat didispatch
setTimeout(() => updateDOM(), 0);

// FIXME: Race condition saat 2 user edit bersamaan
// Perlu implement optimistic locking

// 3. JSDoc — dokumentasi API publik
/**
 * Menghitung harga setelah diskon dan pajak.
 * @param {number} basePrice - Harga dasar produk (dalam Rupiah)
 * @param {number} discountPercent - Persentase diskon (0-100)
 * @returns {number} Harga final setelah diskon dan PPN 11%
 */
function calculateFinalPrice(basePrice, discountPercent) {
  const discounted = basePrice * (1 - discountPercent / 100);
  return discounted * 1.11;
}

// 4. Peringatan penting
// WARNING: Fungsi ini menghapus data PERMANENT, tidak bisa di-undo!
function purgeUserData(userId) { ... }

Komentar yang BERBAHAYA:

// BURUK: komentar yang bohong (kode sudah berubah, komentar tidak)
// Mengembalikan array of active users
function getUsers() {
  return db.users.findAll(); // sebenarnya return SEMUA users!
}

// BURUK: komentar yang kadaluarsa
// Maks 5 item per halaman
const PAGE_SIZE = 20; // sudah diubah, komentar belum

// BURUK: kode yang dikomentari
// function oldImplementation() {
//   const x = doSomething();
//   return x.map(i => process(i));
// }
// HAPUS! Git sudah menyimpan history-nya.

Aturan komentar:

  1. Kode harus self-documenting — komentar adalah opsi terakhir
  2. Jika kamu perlu menulis komentar, tulis mengapa, bukan apa
  3. Jangan biarkan komentar jadi kadaluarsa — update atau hapus
  4. Jangan comment-out kode — hapus, gunakan git untuk history
  5. JSDoc bagus untuk fungsi publik / library / API

🎭 Analogi sehari-hari

Komentar di kode itu kayak sticky note di rumah. Sticky note BAGUS = "Tutup tirai kalau hujan, jendela bocor (perbaikan tukang Senin)" — info kontekstual yang gak kelihatan dari objek itu sendiri. Sticky note JELEK = "Ini lemari" (udah jelas), atau "Tirai biru" (warnanya kelihatan). Lebih buruk lagi: sticky note yang OUTDATED — "Tutup tirai kalau hujan" padahal tirai sudah diganti yang anti-bocor 6 bulan lalu (komentar bohong = miss-direction). Aturan komentar: tulis konteks yang gak self-evident, hapus pas konteks gak relevan, JANGAN tulis "ini paragraf" untuk paragraf yang sudah jelas paragraf.

⚠️ Jebakan yang sering ditemui

Komentar yang BENERAN Berguna

// ✓ Jelaskan KENAPA, bukan APA
// Pakai setTimeout 0 karena DOM belum ready saat dispatch
// (perubahan React 18+ — sebelumnya tidak perlu)
setTimeout(() => focusInput(), 0)

// ✓ Warning untuk side effect
// WARNING: Hapus data permanent, tidak bisa undo
function purgeUser(userId) { ... }

// ✓ Reference ke spec/ticket
// PCI-DSS 3.2.1: store CVV ENCRYPTED only, never plain
function storeCardCVV(cvv) { ... }

// ✓ Magic number explanation
// 86400000 = 24 jam dalam milliseconds
const DAY_MS = 86400000

// ✓ TODO dengan context lengkap
// TODO(ani, 2026-05): migrate ke v2 API setelah backend rilis

🎯 Tulis komentar atau improve kode?

  • "Apa yang kode lakukan" → IMPROVE NAMA, hapus komentar
  • "Kenapa pendekatan ini, bukan yang itu" → komentar OK
  • "Workaround untuk bug eksternal" → komentar wajib (referensi bug ID)
  • "Constraint dari spec/regulasi" → komentar (referensi spec)
  • "Performance reason" → komentar (kasih konteks: profile result, benchmark)
  • "Cara pakai library secara non-obvious" → JSDoc atau comment di pemakaian
  • "Decision history yang penting" → ADR (Architecture Decision Record), bukan inline comment

Aturan emas: kode self-documenting > komentar. Kalau butuh komentar untuk paham kode, tanya: bisa rename variable/fungsi biar paham tanpa komentar?

TL;DR: Komentar = OPSI TERAKHIR. Tulis KENAPA (kontekstual, decision rationale, workaround reason), bukan APA (kode harus self-explanatory). HAPUS komentar yang outdated atau redundan. JANGAN comment-out kode — git history sudah simpan, hapus aja. JSDoc untuk public API/library only. TODO/FIXME wajib include nama + tanggal + konteks. Komentar yang bohong (kode berubah, komentar gak) = lebih buruk dari no comment.