Kód se časem zvětšuje a komplikuje. Programy často píše více lidí nebo se k nim po čase vracíme sami. Proto je důležité mít v kódu i vysvětlení – nejen pro počítač, ale i pro lidi. K tomu slouží tzv. dokumentační komentáře.

V JavaScriptu se používá speciální formát JSDoc, který vypadá takto:

Jak tento zápis funguje?

  • /** ... */ – blokový komentář se dvěma hvězdičkami na začátku, který označuje JSDoc.

  • @param – popis jednoho vstupního parametru funkce:

    • v { } uvádíme očekávaný datový typ (string, number, boolean…),

    • následuje název parametru (jmeno),

    • nakonec krátký popis významu nebo výchozí hodnoty.

  • @returns – podobně popisuje návratovou hodnotu funkce.

Proč je to užitečné?

  • Lepší čitelnost – i složitou funkci pochopíme během několika vteřin.

  • Nápověda v editoru – moderní prostředí (např. VS Code) dokáže JSDoc zobrazit jako bublinu při psaní kódu.

  • Snazší spolupráce – když na kódu pracuje více lidí, nemusí nikdo složitě pátrat, co který parametr znamená.

  • Profesionální praxe – v reálných projektech je dokumentace samozřejmostí, a pokud si na ni zvyknete hned, bude pro vás později přirozená.

Ukázka na jednoduché funkci

Z komentáře je hned jasné, co funkce dělá, co očekává a co vrací.

Mini-šablona, kterou si můžete zkopírovat

Tipy pro psaní dokumentačních komentářů

  1. Pište stručně a jasně – pár slov často stačí.

  2. Uvádějte výchozí hodnoty parametrů (pokud existují).

  3. Používejte JSDoc konzistentně – každá důležitá funkce by měla mít vlastní komentář.

  4. Nezapomeňte na @returns, pokud funkce něco vrací.

Díky těmto komentářům se ve svém kódu rychle zorientujete vy i vaši spolužáci. V následujících úkolech si vyzkoušíte nejen psát funkce, ale i správně je dokumentovat.