Cvičení – vytvoření efektivních komentářů ke kódu

13 min

V tomto cvičení přidáte do kódu poznámky a dočasně zakážete kompilaci určitých řádků kódu. Pak se podíváte, jak kompilátor jazyka C# rozumí prázdným znakům a jak pomocí prázdných znaků zvýšit čitelnost kódu.

Co je komentář ke kódu?

Komentář ke kódu je pokyn kompilátoru, aby na aktuálním řádku ignoroval vše, co je uvedeno za symboly komentáře ke kódu.

// This is a code comment!

Na první pohled se komentář ke kódu nemusí jevit jako užitečný, ale je výhodný ve třech situacích:

Když chcete vložit poznámku týkající se záměru úseku kódu. Může být užitečné zahrnout komentáře ke kódu, které popisují účel nebo myšlenkový proces při psaní zvlášť náročné sady instrukcí kódování. V budoucnu sami sobě poděkujete, že jste takovou poznámku vložili.
Když chcete kód dočasně odebrat z aplikace, abyste vyzkoušeli jiný přístup, ale ještě nejste přesvědčeni, že váš nový nápad bude fungovat. Můžete daný kód okomentovat, napsat nový kód, a až budete přesvědčeni, že nový kód funguje tak, jak chcete, můžete starý (okomentovaný) kód bezpečně odstranit.
Když chcete přidat poznámku (například TODO), která vám připomene, abyste se na daný úsek kódu podívali později. I když byste tuto možnost měli používat uvážlivě, je to užitečný přístup. V době čtení řádku s kódem, který vzbudí vaše obavy, třeba pracujete na jiné funkci. Místo toho, abyste tyto obavy ignorovali, můžete příslušný řádek označit a později prozkoumat.

Poznámka:

Komentáře ke kódu by se měly použít k vyjádření toho, co kód nemůže. Často se stává, že vývojáři aktualizují kód, ale zapomenou aktualizovat komentáře k tomuto kódu. Doporučuje se používat komentáře pro informace vyšší úrovně, nikoli k tomu, jak fungují jednotlivé řádky kódu.

Příprava programovacího prostředí

Tento modul obsahuje cvičení, která vás provedou procesem sestavování a spouštění vzorového kódu. Doporučujeme, abyste tyto aktivity dokončili pomocí editoru Visual Studio Code jako vývojového prostředí. Používání editoru Visual Studio Code pro tyto aktivity vám pomůže stát se pohodlnějším psaním a spouštěním kódu ve vývojářském prostředí, které používají profesionálové po celém světě.

Otevřete Visual Studio Code.

K otevření editoru Visual Studio Code můžete použít windows nabídka Start (nebo ekvivalentní prostředek pro jiný operační systém).
V nabídce Soubor editoru Visual Studio Code vyberte Otevřít složku.
V dialogovém okně Otevřít složku přejděte do složky Windows Desktop.

Pokud máte jiné umístění složky, kde uchováváte projekty kódu, můžete místo toho použít toto umístění složky. Pro toto školení je důležité mít umístění, které je snadné najít a zapamatovat.
V dialogovém okně Otevřít složku vyberte Vybrat složku.

Pokud se zobrazí dialogové okno zabezpečení s dotazem, jestli autorům důvěřujete, vyberte Ano.
V nabídce Terminálu editoru Visual Studio Code vyberte Nový terminál.

Všimněte si, že příkazový řádek na panelu Terminálu zobrazuje cestu ke složce pro aktuální složku. Příklad:
```
C:\Users\someuser\Desktop>
```
Poznámka:

Pokud pracujete na vlastním počítači místo v sandboxu nebo hostovaném prostředí a dokončili jste další moduly Microsoft Learn v této řadě C#, možná jste už vytvořili složku projektu pro ukázky kódu. V takovém případě můžete přeskočit další krok, který se používá k vytvoření konzolové aplikace ve složce TestProject.
Na příkazovém řádku terminálu vytvořte novou konzolovou aplikaci v zadané složce, zadejte následující řádek:
```
dotnet new console -o ./CsharpProjects/TestProject
```
Tento příkaz rozhraní příkazového řádku .NET používá šablonu programu .NET k vytvoření nového projektu konzolové aplikace jazyka C# v zadaném umístění složky. Příkaz pro vás vytvoří složky CsharpProjects a TestProject a jako název souboru .csproj použije TestProject.

Pokud se zobrazí zpráva s oznámením, že soubory už existují, pokračujte dalším postupem. Znovu použijete existující soubory projektu.
V zobrazení PRŮZKUMNÍK rozbalte složku CsharpProjects .

Měla by se zobrazit složka TestProject a dva soubory, programový soubor jazyka C# s názvem Program.cs a soubor projektu C# s názvem TestProject.csproj.
V nabídce Soubor editoru Visual Studio Code vyberte Otevřít složku.
V dialogovém okně Otevřít složku vyberte složku CsharpProjects a pak vyberte Vybrat složku.
V zobrazení PRŮZKUMNÍK rozbalte složku TestProject a pak vyberte Program.cs.
Odstraňte existující řádky kódu.

Tento projekt konzoly C# použijete k vytváření, sestavování a spouštění ukázek kódu během tohoto modulu.
Zavřete panel Terminálu.

Vytváření a používání komentářů ke kódu

V tomto úkolu vytvoříte a odeberete různé typy komentářů ke kódu.

Na panelu Editor editoru sady Visual Studio Code zadejte následující kód:

string firstName = "Bob";
int widgetsSold = 7;
Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");

Pokud chcete kód upravit pomocí komentářů a revizí kódu, aktualizujte kód následujícím způsobem:

string firstName = "Bob";
int widgetsPurchased = 7;
// Testing a change to the message.
// int widgetsSold = 7;
// Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

Projděte si komentáře a aktualizace kódu.

Všimněte si, že komentáře ke kódu slouží k dokumentování potenciální změny a k dočasnému zakázání staré zprávy při testování nové zprávy. Dalším krokem bude otestování aktualizace. Pokud jste s novým kódem spokojení, můžete starý kód, který byl okomentován, bezpečně odstranit. Jedná se o bezpečnější a metodičtější přístup k úpravě pracovního kódu, dokud nepřesvědčíte, že jste připraveni ho trvale odebrat.
V nabídce Soubor editoru Visual Studio Code klepněte na tlačítko Uložit.
Chcete-li v zobrazení PRŮZKUMNÍKa otevřít terminál v umístění složky TestProject, klepněte pravým tlačítkem myši na TestProject a pak vyberte Otevřít v integrovaném terminálu.
Na příkazovém řádku terminálu zadejte příkaz dotnet run a stiskněte Enter.

Měl by se zobrazit následující výstup:
```
Bob purchased 7 widgets.
```
Pokud jste s aktualizacemi spokojeni, odstraňte starý kód, který je zakomentovaný.

Odstraňte komentáře ke kódu.

Teď by měl kód vypadat takto:

string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

Pokud chcete použít blokový komentář, který okomentuje více řádků, aktualizujte kód následujícím způsobem:
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
Blokované komentáře jsou skvělé, pokud potřebujete napsat dlouhý komentář nebo odebrat mnoho řádků kódu. Blokování komentářů se používá /* na začátku kódu a */ na konci. Použití blokového komentáře je nejrychlejším a nejsnadnějším způsobem, jak zakázat tři nebo více řádků kódu.

Nahraďte stávající kód následujícím kódem:

Random random = new Random();
string[] orderIDs = new string[5];
// Loop through each blank orderID
for (int i = 0; i < orderIDs.Length; i++)
{
    // Get a random value that equates to ASCII letters A through E
    int prefixValue = random.Next(65, 70);
    // Convert the random value into a char, then a string
    string prefix = Convert.ToChar(prefixValue).ToString();
    // Create a random number, pad with zeroes
    string suffix = random.Next(1, 1000).ToString("000");
    // Combine the prefix and suffix together, then assign to current OrderID
    orderIDs[i] = prefix + suffix;
}
// Print out each orderID
foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Poznámka:

Tento výpis kódu obsahuje mnoho konceptů jazyka C#, které můžou být pro vás nové. Abyste porozuměli tomu, jak můžou komentáře pomoct čtenářům pochopit účel kódu, není nutné rozumět tomu, co kód provádí.

Chvíli se podívejte, jestli můžete zjistit účel kódu.

Při použití komentářů může být možné zjistit, co kód provádí (za předpokladu, že komentáře přesně popisují aktuální stav a při aktualizaci kódu byly aktualizovány). Dá se ale odhadnout, proč tento kód vůbec existuje? Nebylo by užitečné, kdyby v horní části souboru kódu bylo nějaké vysvětlení, které poskytlo nějaký kontext a popsalo jeho účel?
Zvažte, jak byste komentáře vylepšili.

Všimněte si, že existují dva hlavní problémy s těmito komentáři:
- Komentáře ke kódu zbytečně vysvětlují zjevnou funkčnost jednotlivých řádků kódu. Takové komentáře jsou považovány za nekvalitní, protože jenom vysvětlují, jak funguje jazyk C# nebo metody knihovny tříd .NET. Pokud čtenář tyto myšlenky nezná, může je vyhledat pomocí learn.microsoft.com nebo IntelliSense.
- Komentáře ke kódu neposkytují žádný kontext k problému, který daný kód řeší. Takové komentáře jsou považovány za nekvalitní, protože čtenář nezískává žádné informace o účelu tohoto kódu. Platí to zejména v případě, že daný kód souvisí s větším systémem.

Odeberte existující komentáře.

Teď by měl kód vypadat takto:

Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Všimněte si, že kód je již méně nepotřebný.

Pokud chcete přidat komentář, který vysvětluje účel kódu na vyšší úrovni, aktualizujte kód následujícím způsobem:

/*
  The following code creates five random OrderIDs
  to test the fraud detection process.  OrderIDs 
  consist of a letter from A to E, and a three
  digit number. Ex. A123.
*/
Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Užitečnost komentáře je subjektivní. Ve všech záležitostech souvisejících s čitelností kódu byste měli používat svůj vlastní úsudek. Postupujte způsobem, který je podle vašeho názoru pro zvýšení přehlednosti kódu nejlepší.

Rekapitulace

Hlavní poznatky z tohoto cvičení:

Používejte komentáře ke kódu k tomu, aby vám poskytovaly smysluplné informace o problému, který daný kód řeší.
Nepoužívejte komentáře ke kódu, které vysvětlují, jak funguje jazyk C# nebo knihovna tříd .NET.
Používejte komentáře ke kódu v situacích, kdy chcete dočasně vyzkoušet alternativní řešení. Až budete připraveni řešení s novým kódem potvrdit, můžete starý kód odstranit.
Komentářům nikdy nedůvěřujte. Po provedení mnoha změn a aktualizací komentáře nemusí odrážet aktuální stav kódu.

Váš názor

Byla tato stránka užitečná?