Komentáře

Při psaní kódu si rychle zvyknete, že téměř jakýkoliv symbol nebo slovo, který napíšete, má svůj jedinečný význam. Například, uvidíte mnohokrát klíčová slova, jakými jsou class ("třída"), namespace ("jmenný prostor"), public ("veřejný přístupový modifikátor") a mnoho dalších. Taktéž uvidíte kompilátor se ujišťovat, zdali správně používáte tato klíčová slova, stejně tak jako vaše vlastní proměnné a metody. O C# lze říci, že se jedná o velmi striktní jazyk a kompilátor vám pomůže se ujistit, že vše co jste napsali je správně zadané. Nicméně je zde jediná možnost, jak si psát cokoliv, co se vám zamane a to díky konceptu komentářů.

Nejspíše jste se již setkali s komentáři v kódu, který jste někde viděli, ať už to byl C# nebo jakýkoliv jiný programovací jazyk - koncept komentářů je dosti univerzální. Způsobem, kterým jsou komentáře psány, se mohou lišit, takže se pojďme podívat jaký typ komentářů v C# můžeme použít.

Jednořádkové komentáře

Nejzákladnějším typem komentářů v C# jsou jednořádkové komentáře. Jak název napovídá, převede jeden řádek do komentáře - pojďme se podívat, jak by to kupříkladu mohlo fungovat:

// My comments about the class name could go here...
class Program
{
    ......

Toť vše: Před svůj text napište dvě lomítka (//) a náhle z textu, z kterého by kompilátor nebyl nadšený, se stane naprosto ignorovaný text. A přičemž tohle funguje pouze na označené řádky dvěma lomítky, můžete v klidu udělat stejnou věc i na dalším řádku. V podstatě za používání jednořádkových komentářů udělat komentáře na více řádcích.

// My comments about the class name could go here...
// Add as many lines as you would like
// ...Seriously!
class Program
{
    ...... 

Víceřádkové komentáře

V případě, že chcete napsat více řádků komentářů, může být smysluplnější použít variantu víceřádkového komentáře, kterou nabízí C #. Místo toho, abyste museli předčíslit každý řádek, stačí zadat pořadí znaků začátku a zastavení - vše mezi nimi je považováno za komentáře:

/*  
My comments about the class name could go here...  
Add as many lines of comments as you want  
    ...and use indentation, if you want to!  
*/  
class Program  
{
    ......

Jako začáteční symbol použijte lomítko-hvězdičku (/*). Nyní si pište cokoliv, ať už klidně skrze několik řádků, či nikoliv, následně vše uzavřete konečným symbolem, který se skládá z hvězdičky-lomítka (*/). Mezi tyto dva symboly si můžete psát libovolně, co chcete.

Stejně jako u více dalších programově příbuznými témat, zdali používat násobně jednořádkové komentáře, nebo jeden víceřádkový komentář je často debatováno. Osobně používám obojí pro různé situace - Koneckonců je to čistě na vás!

Dokumentační komentáře

Dokumentační komentáře (někdy označovány jako XML Documentation Comments) vypadají jako běžný komentář, obsahují však vložené XML. Stejně jako běžné komentáře se vyskytují ve dvou variantách: jednořádkové a víceřádkové. Zapisují se také obdobným způsobem, pouze s jedním znakem navíc. Jednořádkové XML dokumentační komentáře začínají třemi lomítky (///) namísto dvou, víceřádková varianta má v počátečním oddělovači navíc jednu hvězdičku (*). Pojďme se podívat, jak to funguje:

class User
{
    /// <summary>
    /// The Name of the User.
    /// </summary>
    public string Name { get; set; }

    /**
    * <summary>The Age of the User.</summary>
    */
    public string Age { get; set; }
}

Zde můžete vidět obě varianty - jednořádkové a víceřádkové. Výsledek je totožný, ale první varianta je obvykle častěji používaná pro dokumentační komentování.

Dokumentování vašich typů a jejich členů za použití dokumentačních komentářů je velmi obsáhlé téma a proto tohle téma bude rozebráno více do hloubky v pozdějším článku, ale aspoň nyní víte, jak vypadají!

Komentáře a Seznam Úkolů

Pokud používáte Visual Studio, můžete si trochu pomoci sledováním vašich komentářů. V okně Seznam Úkolů (Task List), které je zpřístupněno skrze menu View > Task List, se vaše komentáře zobrazí, jestliže používají speciální, ale velmi jednoduchou komentářovou syntaxi Seznamu Úkolů:

//TODO: Change "world" to "universe"
Console.WriteLine("Hello, world!");
//HACK: Don't try this at home....
int answerToLife = 42;

Takže když za jednořádkovým komentářem je napsáno TODO, nebo HACK, zobrazí se v Seznamu Úkolů takto:

A je zde i více typů - záležejících na vaši verzi Visual Studio, které buď budou reagovat na některé nebo na všechny následující komentářové tokeny:

• TODO ("udělat")
• HACK ("zaseknutí")
• NOTE ("poznámka")
• UNDONE ("nehotovo")

Můžete si přidat i vlastní tokeny, pokud chcete - stačí jen následovat kroky popsané v tomto článku.

Shrnutí

Komentáře jsou velmi užitečné, ať už v rámci dokumentování vašeho kódu nebo pro pouhé zanechávání poznámek pro vás či vašeho kolegu, jak dané věci fungují. Jako přidaná výhoda je, že jsou výborné, pokud potřebujete něco rychle otestovat - stačí jen zkopírovat řádek kódu, přidat komentář k původnímu řádku a uvidíte, jak to nyní funguje. Pokud nejste šťastni s výsledkem, můžete prostě smazat nový řádek, odebrat komentář z původní řádky a jste opět tam, kde jste začali.

A nebojte se, že konečný uživatel bude procházet vaše komentáře - jak již bylo řečeno, komentáře jsou zcela ignorovány kompilátorem a proto nejsou ani obsaženy ve vašich výsledných DLL nebo EXE souborech. Komentáře v kódu je takový váš osobní prostor při programování, tudíž je můžete využívat, jakým způsobem chcete.