CKTIS / JavaScript
Komentarze i dokumentacja
Komentarze opisują zamiar kodu bez wykonywania swojej treści. Poznaj zapis // i /* ... */, konwencję dokumentacyjną /** ... */ oraz wpływ końców linii na interpretację programu.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
// comment
/* block comment */
/** documentation comment */Komentarze służą do objaśniania kodu, zwłaszcza powodów decyzji i ograniczeń. Ich treść nie jest wykonywana jako JavaScript. Zalecenie redakcyjne: opisuj przede wszystkim „dlaczego”, zamiast powtarzać oczywiste działanie instrukcji.
// rozpoczyna komentarz do końca linii lub źródła; znak końca linii nie należy do komentarza. /* ... */ może zajmować część linii albo wiele linii i kończy się na pierwszym */. Komentarzy blokowych nie można zagnieżdżać.
/** ... */ jest dla ECMAScript zwykłym komentarzem blokowym. Zapis dokumentacyjny nie zmienia działania funkcji ani nie wymusza typów; interpretacja dodatkowych oznaczeń należy do narzędzi, a nie do składni języka.
Komentarze zachowują się jak białe znaki, z ważnym wyjątkiem: komentarz blokowy zawierający znak końca linii jest podczas analizy składniowej traktowany jak koniec linii. Może to wpłynąć na automatyczne wstawianie średników (ASI), np. po return. Nie rozdzielaj return i zwracanej wartości takim komentarzem. Osobna forma #! jest dozwolona wyłącznie na samym początku źródła skryptu lub modułu.
Przykłady
/** Compute the total price. */
function total(price, quantity) {
// Keep the calculation in one place.
return price * quantity;
}
const result = total(7, /* quantity */ 3);
console.log(result);Wynik
21
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.