Komentarze w JavaScript: jednoliniowe, blokowe i kiedy ich używać

Dwa rodzaje komentarzy

JavaScript ma dwie składnie komentarzy. Komentarz jednoliniowy zaczyna się od // i trwa do końca linii:

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

console.log(price);

Komentarz blokowy zaczyna się od /* i kończy na najbliższym */. Może zajmować tyle linii, ile chcesz:

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

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

Silnik JavaScript całkowicie ignoruje obie formy. Istnieją dla ludzi: dla ciebie, dla twojego zespołu i dla ciebie za pół roku, gdy wrócisz do tego kodu.

Komentarze jednoliniowe

// to forma, której będziesz używać najczęściej. Wszystko w tej samej linii za // jest komentarzem, a następna linia znowu jest kodem:

// 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);

Komentarze na końcu linii (za instrukcją) są w porządku przy krótkich notatkach. Jeśli notatka robi się na tyle długa, że się zawija, przenieś ją do osobnej linii nad kodem: długie komentarze końcowe edytory ucinają, a czytelnicy ignorują.

Komentarze blokowe

Po /* */ warto sięgać w dwóch przypadkach: gdy komentarz potrzebuje więcej niż jednej linii i gdy stoi w środku wyrażenia.

/*
 * 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);

Jedna pułapka: komentarze blokowe się nie zagnieżdżają. Pierwsze */ kończy komentarz, nawet jeśli wydaje ci się, że wciąż jesteś w zewnętrznym:

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

Jeśli musisz zakomentować kod, który już zawiera /* */, użyj zamiast tego // w każdej linii.

Zakomentowywanie kodu

Podczas debugowania często chcesz tymczasowo wyłączyć kilka linii. Działają obie formy komentarzy:

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 }]));

Każdy edytor ma do tego skrót: Ctrl+/ na Windows/Linux, Cmd+/ na Macu. Przełącza on // w zaznaczonych liniach. Naucz się go raz, a będziesz go używać codziennie.

Zakomentowany kod ma być tymczasowy. Nie commituj cmentarzysk martwego kodu z dopiskiem // old version, keep just in case nad nimi. System kontroli wersji pamięta stary kod za ciebie. Usuń go.

Komentuj dlaczego, a nie co

To jedyna reguła, która oddziela przydatne komentarze od szumu. Kod już pokazuje, co robi. Dobry komentarz wyjaśnia, dlaczego.

Szum:

// 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);
}

Te komentarze nie mówią czytelnikowi niczego, czego kod już nie powiedział. Porównaj:

// 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}`);
    }
}

Oba komentarze odwołują się do czegoś, czego czytelnik nie wywnioskuje z samego kodu: zewnętrznego ograniczenia, udokumentowanego dziwactwa. To jest poprzeczka. Jeśli po usunięciu komentarza nikt nie byłby zdezorientowany, komentarz nie był wart swojego miejsca.

JSDoc: komentarze czytane przez narzędzia

JSDoc to konwencja pisania komentarzy blokowych, które w ustrukturyzowany sposób opisują funkcje. Edytory i narzędzia do sprawdzania typów je czytają i dają ci lepsze autouzupełnianie i dokumentację po najechaniu kursorem:

/**
 * 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));

To otwarcie /** (dwie gwiazdki) oznacza JSDoc, a nie zwykły komentarz blokowy. Nie potrzebujesz JSDoc przy każdej funkcji: najbardziej opłaca się przy publicznych API, współdzielonych narzędziach i wszędzie tam, gdzie typy nie są oczywiste z samego kodu.

Kilka nawyków, które warto zachować

• Trzymaj komentarze blisko kodu, który opisują. Komentarz dziesięć linii nad właściwą linią łatwo rozjeżdża się z kodem, gdy ten się zmienia.
• Aktualizuj komentarze, gdy zmieniasz kod. Nieaktualny komentarz jest gorszy niż żaden: aktywnie okłamuje następnego czytelnika.
• Wybieraj lepsze nazwy zamiast większej liczby komentarzy. const d = 86400000; potrzebuje komentarza. const MILLISECONDS_PER_DAY = 86_400_000; nie.
• Oznaczaj tymczasowe problemy przez TODO: albo FIXME:. Większość edytorów je podświetla i łatwo później je wyszukać grepem.

// TODO: poprawnie obsłużyć przesunięcia stref czasowych po aktualizacji biblioteki dat
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));

Uwaga o komentarzach HTML i JavaScript

Jeśli piszesz JavaScript w pliku HTML, nie myl tych dwóch stylów komentarzy. HTML używa <!-- -->, a JavaScript // i /* */. Wewnątrz znacznika <script> działają tylko formy z JavaScriptu:

<script>
    // Dobrze: komentarz JS wewnątrz <script>
    /* Też dobrze */
    <!-- Źle: to komentarz HTML, który zepsuje twój JS -->
    console.log("cześć");
</script>

Przeglądarki historycznie tolerowały <!-- --> w skryptach z powodu bardzo starych przeglądarek, ale traktuj to jako błąd i idź dalej.

Dalej: deklarowanie zmiennych

Skoro umiesz już opisywać kod, czas go pisać. JavaScript ma trzy sposoby deklarowania zmiennej: let, const i var, a wybór właściwego to pierwsza prawdziwa decyzja, którą podejmujesz przy każdej linii. O tym jest następna strona.