Memahami Gaya Penulisan Comment dalam Code (dan Kapan Harus Menggunakannya)

Menulis comment bukan sekadar menambahkan teks penjelasan di dalam kode. Comment yang baik membantu orang lain (dan diri sendiri di masa depan) memahami niat, konteks, dan alasan di balik kode, bukan hanya “apa yang dilakukan”.

Namun, tidak semua comment dibuat dengan tujuan yang sama. Ada beberapa gaya penulisan comment yang umum digunakan, dan masing-masing punya fungsi yang berbeda.

---

1. JSDoc (/** ... */) — Untuk Dokumentasi dan API

Ini adalah jenis comment yang paling “formal”. Biasanya digunakan untuk mendokumentasikan:

• Function atau method
• Class
• Module
• Public API

Selain dibaca manusia, JSDoc juga bisa digunakan oleh:

• IDE (untuk autocomplete & hint)
• Tools dokumentasi

Contoh:

/**
 * Calculate total price including tax.
 *
 * @param price - base price
 * @param taxRate - tax percentage (e.g. 0.1 for 10%)
 * @returns total price after tax
 */
function calculateTotal(price: number, taxRate: number): number {
  return price + price * taxRate;
}

Kapan digunakan:

• Saat membuat function yang akan digunakan ulang
• Saat menulis library atau shared code
• Saat logic butuh penjelasan yang jelas dan terstruktur

---

2. Short JSDoc (/** comment */) — Penjelasan Singkat tapi Penting

Ini adalah versi ringkas dari JSDoc. Biasanya digunakan untuk menjelaskan satu baris atau blok kecil yang tetap butuh konteks tambahan.

Contoh:

/** Ensure user is authenticated before accessing data */
if (!user) {
  throw new Error('Unauthorized');
}

Kapan digunakan:

• Untuk menjelaskan intent dari suatu blok kecil
• Saat komentar terlalu penting untuk pakai //, tapi tidak perlu panjang

---

3. Inline Comment (// ...) — Catatan Cepat

Ini adalah jenis comment paling sederhana dan fleksibel.

Contoh:

// Skip inactive users
const activeUsers = users.filter(user => user.isActive);

Kapan digunakan:

• Untuk penjelasan ringan
• Klarifikasi cepat
• Catatan sementara saat development

---

Kesalahan Umum yang Harus Dihindari

❌ 1. Menjelaskan hal yang sudah jelas

// increment i
i++;

👉 Ini tidak memberi nilai tambah.

---

❌ 2. Comment terlalu panjang dengan //

// this function checks if the user exists and if not throws an error and also logs the activity

👉 Lebih baik gunakan /** ... */ agar lebih rapi dan terbaca.

---

❌ 3. Comment tidak menjelaskan “kenapa”

// sort array
items.sort();

👉 Lebih baik:

// Sort items by priority (highest first)
items.sort((a, b) => b.priority - a.priority);

---

Prinsip Penting dalam Menulis Comment

1. Fokus pada “Why”, bukan “What”

Kode sudah menjelaskan apa yang dilakukan. Comment harus menjelaskan kenapa.

2. Hindari komentar yang basi

Jika kode berubah tapi comment tidak di-update, itu lebih berbahaya daripada tidak ada comment.

3. Gunakan gaya yang konsisten

Dalam satu project, gunakan pola yang sama agar mudah dibaca oleh tim.

---

Rekomendasi Praktis

Kebutuhan	Gunakan
Dokumentasi function / API	/** ... */
Penjelasan singkat tapi penting	/** ... */
Catatan ringan	//

---

Contoh Kombinasi yang Baik

/**
 * Process payment and return transaction result.
 * Will throw an error if payment fails.
 */
async function processPayment(amount: number) {
  /** Validate minimum amount */
  if (amount <= 0) {
    throw new Error('Invalid amount');
  }

  // Call external payment service
  const result = await paymentService.charge(amount);

  return result;
}

---

Penutup

Menulis comment yang baik bukan tentang membuat kode terlihat “lebih profesional”, tapi tentang:

• Membuat kode lebih mudah dipahami
• Mengurangi kebingungan di masa depan
• Mempermudah kolaborasi tim

Gunakan jenis comment yang tepat sesuai kebutuhan. Terlalu sedikit comment bisa membingungkan, tapi terlalu banyak juga bisa jadi “noise”.

Kuncinya adalah: jelas, relevan, dan konsisten.