Komentáře

Jak víme z kapitoly Struktura kódu, komentáře mohou být jednořádkové:začínající // a víceřádkový:/* ... */ .

Obvykle je používáme k popisu toho, jak a proč kód funguje.

Na první pohled mohou být komentáře zřejmé, ale nováčci v programování je často používají špatně.

Špatné komentáře

Začátečníci mají tendenci používat komentáře k vysvětlení „co se děje v kódu“. Takhle:

// This code will do this thing (...) and that thing (...)
// ...and who knows what else...
very;
complex;
code;

Ale v dobrém kódu by množství takových „vysvětlujících“ komentářů mělo být minimální. Vážně, kód by měl být snadno srozumitelný i bez nich.

Existuje na to skvělé pravidlo:„Pokud je kód tak nejasný, že vyžaduje komentář, možná by měl být místo toho přepsán.“

Recept:vyloučení funkcí

Někdy je užitečné nahradit část kódu funkcí, například zde:

function showPrimes(n) {
 nextPrime:
 for (let i = 2; i < n; i++) {

 // check if i is a prime number
 for (let j = 2; j < i; j++) {
 if (i % j == 0) continue nextPrime;
 }

 alert(i);
 }
}

Lepší varianta s vyřazenou funkcí isPrime :

function showPrimes(n) {

 for (let i = 2; i < n; i++) {
 if (!isPrime(i)) continue;

 alert(i);
 }
}

function isPrime(n) {
 for (let i = 2; i < n; i++) {
 if (n % i == 0) return false;
 }

 return true;
}

Nyní kód snadno pochopíme. Samotná funkce se stává komentářem. Takový kód se nazývá sebepopisný .

Recept:vytvoření funkcí

A pokud máme dlouhý „kódový list“, jako je tento:

// here we add whiskey
for(let i = 0; i < 10; i++) {
 let drop = getWhiskey();
 smell(drop);
 add(drop, glass);
}

// here we add juice
for(let t = 0; t < 3; t++) {
 let tomato = getTomato();
 examine(tomato);
 let juice = press(tomato);
 add(juice, glass);
}

// ...

Pak by mohlo být lepší variantou jej předělat na funkce jako:

addWhiskey(glass);
addJuice(glass);

function addWhiskey(container) {
 for(let i = 0; i < 10; i++) {
 let drop = getWhiskey();
 //...
 }
}

function addJuice(container) {
 for(let t = 0; t < 3; t++) {
 let tomato = getTomato();
 //...
 }
}

Ještě jednou, funkce samy řeknou, co se děje. není co komentovat. A také struktura kódu je lepší, když je rozdělena. Je jasné, co každá funkce dělá, co bere a co vrací.

Ve skutečnosti se nemůžeme zcela vyhnout „vysvětlujícím“ komentářům. Existují složité algoritmy. A existují chytré „vychytávky“ pro účely optimalizace. Obecně bychom se ale měli snažit, aby byl kód jednoduchý a popisný.

Dobré komentáře

Takže vysvětlující komentáře jsou obvykle špatné. Které komentáře jsou dobré?

Popište architekturu

Poskytněte přehled komponent na vysoké úrovni, jak interagují, jaký je tok ovládání v různých situacích... Zkrátka – pohled na kód z ptačí perspektivy. Existuje speciální jazyk UML pro vytváření diagramů architektury na vysoké úrovni vysvětlujících kód. Rozhodně stojí za prostudování.

Parametry a použití funkcí dokumentu

Pro dokumentování funkce existuje speciální syntaxe JSDoc:použití, parametry, vrácená hodnota.

Například:

/**
 * Returns x raised to the n-th power.
 *
 * @param {number} x The number to raise.
 * @param {number} n The power, must be a natural number.
 * @return {number} x raised to the n-th power.
 */
function pow(x, n) {
 ...
}

Takové komentáře nám umožňují pochopit účel funkce a použít ji správným způsobem, aniž bychom museli hledat v jejím kódu.

Mimochodem, mnoho editorů, jako je WebStorm, jim také rozumí a používá je k automatickému doplňování a automatické kontrole kódu.

Existují také nástroje jako JSDoc 3, které dokážou generovat HTML dokumentaci z komentářů. Další informace o JSDoc si můžete přečíst na https://jsdoc.app.

Proč je úloha vyřešena tímto způsobem?

Důležité je, co je napsáno. Ale co není napsané může být ještě důležitější pro pochopení toho, co se děje. Proč je úloha řešena právě tímto způsobem? Kód nedává žádnou odpověď.

Pokud existuje mnoho způsobů řešení úkolu, proč tento? Zvlášť když to není nejzřetelnější.

Bez těchto komentářů je možná následující situace:

1. Vy (nebo váš kolega) otevřete kód napsaný před nějakou dobou a uvidíte, že není „optimální“.
2. Pomyslíte si:„Jak jsem byl tehdy hloupý a o kolik jsem teď chytřejší“ a přepište pomocí varianty „jasnější a správnější“.
3. …Tuha přepsat byla dobrá. Ale v procesu vidíte, že „jasnější“ řešení ve skutečnosti chybí. Dokonce si matně pamatujete proč, protože jste to už dávno zkusili. Vrátíte se ke správné variantě, ale čas byl ztracen.

Komentáře, které vysvětlují řešení, jsou velmi důležité. Pomáhají pokračovat ve vývoji správným způsobem.

Nějaké jemné rysy kódu? Kde se používají?

Pokud má kód něco jemného a neintuitivního, rozhodně to stojí za komentář.

Shrnutí

Důležitým znakem dobrého vývojáře jsou komentáře:jejich přítomnost a dokonce i jejich nepřítomnost.

Dobré komentáře nám umožňují kód dobře udržovat, vracet se k němu po prodlevě a používat jej efektivněji.

Komentujte toto:

• Celková architektura, zobrazení na vysoké úrovni.
• Využití funkcí.
• Důležitá řešení, zvláště když nejsou okamžitě zřejmá.

Vyhýbejte se komentářům:

• To říká, „jak kód funguje“ a „co dělá“.
• Vkládejte je pouze v případě, že není možné, aby byl kód tak jednoduchý a popisný, že je nevyžaduje.

Komentáře se také používají pro nástroje pro automatickou dokumentaci, jako je JSDoc3:čtou je a generují dokumenty HTML (nebo dokumenty v jiném formátu).