Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

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.

Źródła