Komentar JavaScript: Satu Baris, Blok, dan Kapan Memakainya

Dua Jenis Komentar

JavaScript punya dua sintaks komentar. Komentar satu baris dimulai dengan // dan berlaku sampai akhir baris:

// This is a single-line comment
let price = 100; // Comments can also trail code

console.log(price);

Komentar blok dimulai dengan /* dan berakhir di */ berikutnya. Komentar ini bisa mencakup sebanyak apa pun baris yang kamu mau:

/*
  This is a block comment.
  It spans multiple lines.
  The interpreter ignores all of it.
*/

let total = 42;
console.log(total);

Kedua bentuk ini sepenuhnya diabaikan oleh engine JavaScript. Komentar ada untuk manusia: untukmu, untuk rekan setimmu, dan untuk dirimu sendiri yang membaca kode ini enam bulan lagi.

Komentar Satu Baris

// adalah yang paling sering kamu pakai. Apa pun yang ada di baris yang sama setelah // adalah komentar; baris berikutnya kembali menjadi kode:

// Calculate the tax-inclusive price
const price = 100;
const taxRate = 0.08;
const total = price * (1 + taxRate); // final amount the customer pays

console.log(total);

Komentar di belakang pernyataan cocok untuk catatan pendek. Kalau catatannya cukup panjang sampai terpotong ke baris baru, pindahkan ke barisnya sendiri di atas kode. Komentar panjang di ujung baris sering terpotong di editor dan diabaikan pembaca.

Komentar Blok

/* */ layak dipakai dalam dua situasi: komentar yang butuh lebih dari satu baris, dan komentar yang berada di tengah sebuah ekspresi.

/*
 * Applies a bulk discount when the order qualifies.
 * Rules change per quarter - see pricing spec #214.
 */
function bulkDiscount(quantity, unitPrice) {
    return quantity >= 10 ? unitPrice * 0.9 : unitPrice;
}

// Inline in the middle of an expression:
const area = /* width */ 10 * /* height */ 5;

console.log(bulkDiscount(12, 50));
console.log(area);

Ada satu jebakan: komentar blok tidak bisa bersarang. */ pertama mengakhiri komentar, walaupun kamu kira masih berada di dalam komentar luar:

/* outer /* inner */ still outer */
// SyntaxError - the first */ closed the block,
// and "still outer */" is now invalid code.

Kalau kamu perlu menonaktifkan kode yang sudah berisi /* */, pakai // di setiap barisnya.

Menonaktifkan Kode dengan Komentar

Saat sedang debug, kamu sering ingin mematikan beberapa baris untuk sementara. Kedua bentuk komentar bisa dipakai:

function checkout(cart) {
    const subtotal = cart.reduce((sum, item) => sum + item.price, 0);

    // const shipping = calculateShipping(cart);
    // const total = subtotal + shipping;

    /*
    if (cart.length === 0) {
        throw new Error("Cart is empty");
    }
    */

    return subtotal;
}

console.log(checkout([{ price: 10 }, { price: 20 }]));

Setiap editor punya shortcut untuk ini, yaitu Ctrl+/ di Windows/Linux dan Cmd+/ di Mac, yang menyalakan atau mematikan // pada baris yang dipilih. Pelajari sekali saja; kamu akan memakainya setiap hari.

Kode yang dijadikan komentar seharusnya hanya sementara. Jangan commit tumpukan kode mati dengan // old version, keep just in case di atasnya. Version control sudah mengingat kode lama untukmu. Hapus saja.

Jelaskan Alasannya, Bukan Apa yang Dilakukan

Inilah satu aturan yang membedakan komentar yang berguna dari gangguan. Kode sudah menunjukkan apa yang dilakukannya. Komentar yang bagus menjelaskan mengapa.

Gangguan:

// Set x to 10
let x = 10;

// Loop through the array
for (let i = 0; i < x; i++) {
    // Add i to the total
    console.log(i);
}

Komentar-komentar itu tidak memberi tahu pembaca apa pun yang belum dikatakan kodenya. Bandingkan dengan ini:

// Stripe caps description at 500 chars - truncate before sending
function prepareDescription(text) {
    return text.slice(0, 500);
}

// Retry once: the auth service has a known cold-start timeout on first request
async function fetchUser(id) {
    try {
        return await api.get(`/users/${id}`);
    } catch {
        return await api.get(`/users/${id}`);
    }
}

Kedua komentar itu menyebut sesuatu yang tidak bisa dipahami pembaca hanya dari kodenya: batasan dari luar, atau keanehan yang sudah diketahui. Itulah standarnya. Kalau menghapus komentar tidak membuat siapa pun bingung, berarti komentar itu tidak berguna.

JSDoc: Komentar yang Dibaca Tools

JSDoc adalah konvensi menulis komentar blok yang menjelaskan fungsi secara terstruktur. Editor dan type checker membacanya lalu memberimu autocomplete dan dokumentasi saat hover yang lebih baik:

/**
 * Returns the final price after applying a percentage discount.
 *
 * @param {number} price - The original price in cents.
 * @param {number} percent - Discount percentage, 0 to 100.
 * @returns {number} The discounted price in cents.
 */
function discount(price, percent) {
    return price * (1 - percent / 100);
}

console.log(discount(10000, 20));

Pembuka /** (dua bintang) itulah yang menandainya sebagai JSDoc, bukan komentar blok biasa. Kamu tidak perlu JSDoc di setiap fungsi. JSDoc paling berguna untuk API publik, utilitas yang dipakai bersama, dan di mana pun tipenya belum jelas dari kode.

Beberapa Kebiasaan yang Layak Dipertahankan

• Letakkan komentar dekat dengan kode yang dijelaskannya. Komentar yang berada sepuluh baris di atas baris terkait cenderung tidak lagi sesuai saat kodenya berubah.
• Perbarui komentar saat kamu mengubah kode. Komentar yang usang lebih buruk daripada tidak ada komentar, karena komentar itu membohongi pembaca berikutnya.
• Utamakan nama yang lebih baik daripada komentar yang lebih banyak. const d = 86400000; butuh komentar. const MILLISECONDS_PER_DAY = 86_400_000; tidak.
• Tandai masalah sementara dengan TODO: atau FIXME:. Kebanyakan editor menyorotnya, dan keduanya mudah dicari dengan grep nanti.

// TODO: handle timezone offsets properly once the date library is upgraded
function daysBetween(a, b) {
    const MS_PER_DAY = 86_400_000;
    return Math.round((b - a) / MS_PER_DAY);
}

const start = new Date("2024-01-01");
const end = new Date("2024-01-15");
console.log(daysBetween(start, end));

Catatan tentang Komentar HTML dan JavaScript

Kalau kamu menulis JavaScript di dalam file HTML, jangan tertukar antara dua gaya komentar ini. HTML memakai <!-- -->; JavaScript memakai // dan /* */. Di dalam tag <script>, hanya bentuk JavaScript yang berfungsi:

<script>
    // Correct - JS comment inside <script>
    /* Also correct */
    <!-- Wrong - this is an HTML comment and will break your JS -->
    console.log("hi");
</script>

Dulu browser menoleransi <!-- --> di dalam script demi browser yang sangat tua, tetapi anggap saja itu rusak dan jangan dipakai.

Berikutnya: Mendeklarasikan Variabel

Sekarang kamu sudah bisa memberi keterangan pada kode, saatnya menulis kode. JavaScript punya tiga cara untuk mendeklarasikan variabel, yaitu let, const, dan var, dan memilih yang tepat adalah keputusan nyata pertama yang akan kamu buat di setiap baris. Itu topik berikutnya.