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…

Komentar yang baik menjelaskan kenapa, bukan apa. Apa yang dikerjakan kode sudah tertulis di kodenya; yang gak kelihatan adalah alasannya. Bayangin catatan tempel di laci gudang Toko Kaos Raka. "Laci" di laci itu gak berguna, semua orang sudah lihat itu laci. "Laci ini macet, angkat sedikit baru tarik" berguna, karena itu gak kelihatan dari lacinya. Yang paling buruk: catatan "isi: kaos hitam" padahal isinya sudah ganti topi. Catatan yang bohong lebih menyesatkan daripada gak ada catatan.

🧪 Tebakan cepat: Raka menaikkan batas gratis ongkir jadi Rp 250.000. Developer mengubah konstantanya, tapi komentar di sebelahnya masih bilang 200000. Keranjang A tanpa voucher (Rp 245.000): menurut komentar totalnya berapa, menurut kode berapa? Tebak dulu, jawabannya ada di bagian "Komentar yang mengulang kode ikut basi".

Komputer melewati komentar

Ini kasir Toko Kaos Raka yang diberi komentar di tiap baris:

const VOUCHER_DISCOUNT = 0.1; // diskon 0.1
const FREE_SHIPPING_MIN = 200000; // gratis ongkir mulai 200000
const SHIPPING_FEE = 15000; // ongkir 15000

function calculateTotal(cart, voucherCode) {
  let total = 0; // total mulai dari 0
  // loop semua item
  for (const item of cart) {
    total += item.price * item.qty; // tambah harga kali qty
  }
  // kalau voucher HEMAT10, potong 10%
  if (voucherCode === 'HEMAT10') total -= total * VOUCHER_DISCOUNT;
  // kalau total di bawah 200000, tambah ongkir
  if (total < FREE_SHIPPING_MIN) total += SHIPPING_FEE;
  return 'Total: Rp ' + total.toLocaleString('id-ID'); // kembalikan total
}

Sembilan komentar, dan semuanya cuma membaca ulang kodenya dalam bahasa Indonesia. Hapus semuanya, jalankan empat keranjang: Total: Rp 220.500, Rp 245.000, Rp 90.000, Rp 204.000, sama persis. Komputer melewati semua yang ada setelah //. Komentar cuma untuk manusia, jadi ukurannya: apakah ia memberi tahu manusia sesuatu yang belum tertulis di kode?

Komentar yang mengulang kode ikut basi

Raka menaikkan batasnya. Developer mengubah satu angka:

const FREE_SHIPPING_MIN = 250000; // gratis ongkir mulai 200000

Dua komentar sekarang bohong: yang ini dan "kalau total di bawah 200000, tambah ongkir". Pembaca yang percaya komentar menebak keranjang A tanpa voucher (245.000) gratis ongkir, jadi Total: Rp 245.000. Kodenya menagih Total: Rp 260.000, karena 245.000 di bawah 250.000. Itu jawaban tebakannya. Gak ada error, cuma dua sumber yang gak cocok, persis masalah duplikasi di lesson DRY: angka yang ditulis di komentar adalah salinan kedua dari konstanta, dan salinan kedua gampang lupa diubah.

Komentar yang menjelaskan kenapa

Versi yang sama dengan dua komentar yang gak bisa dibaca dari kode:

const VOUCHER_DISCOUNT = 0.1;
// Keputusan Raka (rapat Maret): toko menanggung ongkir kalau belanjanya
// cukup besar untuk menutup biaya kirim. Tanya Raka sebelum mengubah.
const FREE_SHIPPING_MIN = 200000;
const SHIPPING_FEE = 15000;

function calculateTotal(cart, voucherCode) {
  let total = 0;
  for (const item of cart) {
    total += item.price * item.qty;
  }
  if (voucherCode === 'HEMAT10') total -= total * VOUCHER_DISCOUNT;
  // Ongkir dicek SETELAH voucher: batasnya dihitung dari uang yang benar-benar
  // dibayar pembeli. Keranjang D di test menjaga urutan ini.
  if (total < FREE_SHIPPING_MIN) total += SHIPPING_FEE;
  return 'Total: Rp ' + total.toLocaleString('id-ID');
}

Hal lain yang pantas jadi komentar: workaround untuk batasan di luar kodemu, misalnya // Workaround: Safari tidak support IntersectionObserver v2, alasan dari aturan atau regulasi, dan peringatan seperti // Menghapus data permanen, tidak bisa di-undo.

Sebelum menulis komentar, coba ganti nama

Komentar yang menjelaskan apa biasanya tanda nama yang kurang jelas:

const d = 86400000; // milidetik dalam sehari
const MS_PER_DAY = 86400000;

Baris kedua gak butuh komentar. Sama untuk fungsi: getData() dengan komentar tiga baris lebih baik diganti nama yang menjelaskan dirinya. Kode lama yang di-comment-out "siapa tahu perlu" dihapus saja, karena git sudah menyimpan riwayatnya. Penanda TODO boleh, asal ada konteksnya: siapa, kapan, dan kenapa.

Latihan: sesi login

Di latihan, isSessionValid penuh komentar yang mengulang kode, dan angka 3600000 gak bernama:

  1. Hapus komentar yang mengulang kode, termasuk // return hasil perbandingan.
  2. Pindahkan 3600000 ke const SESSION_TIMEOUT_MS = 3600000; (3.600.000 milidetik = 1 jam), pakai di fungsi, dan beri komentar kenapa: kebijakan keamanan, sesi yang gak aktif kedaluwarsa setelah 1 jam.
  3. Tambahkan // TODO: pindahkan ke config env tepat di atas const API_KEY, yang sudah ada dan tetap.

Output-nya tetap true lalu false. Fungsinya juga diuji sendiri: isSessionValid(0, 3600001) harus false (lewat satu jam), dan isSessionValid(3600000, 3600001) harus true, karena yang dibandingkan adalah selisih now - lastActivity.

⚠️ Jebakan yang sering ketemu

TL;DR: Komentar menjelaskan kenapa, bukan apa; komputer melewatinya, jadi ukurannya adalah apakah ia memberi tahu manusia sesuatu yang belum tertulis di kode. Sembilan komentar yang membaca ulang kasir gak mengubah satu pun hasil, dan begitu batas gratis ongkir naik ke 250.000, komentar yang menyalin angka 200000 jadi bohong: keranjang A tanpa voucher "gratis ongkir" menurut komentar, Total: Rp 260.000 menurut kode. Komentar yang berguna menyimpan alasan (keputusan Raka, kenapa ongkir dicek setelah voucher), workaround, aturan dan peringatan. Hapus komentar yang cuma menjelaskan apa yang sudah jelas dari kode, ganti nama sebelum menulis komentar, dan hapus kode yang di-comment-out. Di latihan: hapus komentar redundan, SESSION_TIMEOUT_MS = 3600000 dengan komentar kebijakan 1 jam, // TODO: pindahkan ke config env di atas API_KEY, output true lalu false.

Yang akan kamu pelajari