Коментари

Током писања програмског кôда добра пракса налаже да требате редовно писати коментаре у којима ћете кôд образложити. Када анализирате ваш кôд који сте написали раније, коментари ће вам помоћи да се присетите и разумете шта сте тачно радили. Можда ово звучи смешно или непотребно, али један програмер током радног века највероватније ради на много различитих пројеката, па кôд који је раније писао може да му изгледа као да га је писао неко други. Следећи разлог је колегијалност или тимски рад. Ако други програмер треба да анализира и користи ваш кôд, коментари ће му помоћи да га боље разуме. У већини софтверских компанија је писање коментара унифицирано, стандардизовано и уређено разним правилницима. Аргумент против писања коментара гласи: “Ако је за кôд потребан коментар, онда је кôд лоше написан” – не препоручујем вам да ово усвојите.

Шта треба писати у коментарима? Коментари треба да дефинишу шта је написано и објасне зашто, а у кôду ће се видети како. Уколико програмер који није учествовао у развоју програма може да разуме како програм функционише на основу коментара и кôда, онда су коментари добро написани.

У програмском језику C# коментаре пишемо на два начина: у једном реду (тзв. једнолинијски коментари, Single-Line Comments) или у више редова (тзв. вишелинијски или блок коментари, Multiple-Line Comments).

Једнолинијски коментари почињу са //. Било који текст који унесемо после // па све до краја реда биће игнорисан од стране C# компајлера. У овом примеру коментар почиње од почетка реда:

// Ovo je komentar
Console.WriteLine("Hello World!");

а у овом, након линије кôда:

Console.WriteLine("Hello World!");  // Ovo je komentar

Вишелинијски коментари почињу са /* и завршавају се са */. Било који текст који унесемо између /* и */ биће игнорисан од стране C# компајлера. На пример:

/* Kôd koji sledi ispisaće tekst "Hello World!" u jednoj liniji konzole
   pomoću metode WriteLine */
Console.WriteLine("Hello World!"); 

Обично се // користи за кратке коментаре или за привремено спречавање извршавања одређење линије кôда, а /* */ за дуже коментаре.

Генерисање XML документације

Програмски језик C# поседује и посебну врсту коментара који служе за генерисање XML програмске документације. Документацијски коментари почињу са /// након чега се додаје документацијски XML таг. Постоје многобројни документацијски тагови, а можете да креирате и своје.

Коришћење документацијских коментара демонстрираћемо на једноставном примеру:

using System;
/// <summary> Klasa Hello koja ispisuje poruku u konzoli.
/// </summary>
class Hello {
    /// <remarks> U kôdu koristimo konzolni I/O. Za
    /// više informacija o metodi WriteLine, pogledajte:
    /// <seealso cref="System.Console.WriteLine()"/>
    /// </remarks>
    static void Main() {
        Console.WriteLine("Hello, World!");
    }
}

XML таг summary користили смо за писање сажетог описа. За детаљнији опис користили смо таг remarks. Тагом seealso креирали смо референцу ка System.Console.WriteLine() (компајлер проверава да ли стварно постоји!). XML документацију компајлирамо из командне линије на следећи начин:

csc Program.cs /doc:Dokumentacija.xml

Извршавањем ове команде у фолдеру у коме је сачуван наш програм (у фајлу Program.cs), генерисали смо XML фајл Dokumentacija.xml са следећим садржајем:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Program</name>
    </assembly>
    <members>
        <member name="T:Hello">
            <summary> Klasa Hello koja ispisuje poruku u konzoli.
            </summary>
        </member>
        <member name="M:Hello.Main">
            <remarks> U kôdu koristimo konzolni I/O. Za
            više informacija o metodi WriteLine, pogledajte:
            <seealso cref="M:System.Console.WriteLine"/>
            </remarks>
        </member>
    </members>
</doc>

Ако у командној линији добијете грешку ‘csc’ is not recognized as an internal or external command, operable program or batch file. значи да на вашем рачунару за извршни фајл csc.exe није дефинисана путања (PATH). У том случају потребно је или да дефинишете путању за csc.exe (који се налази у фолдеру Windows\Microsoft.NET\Framework\verzija) или да користите Developer Command Prompt for VS 2019 у коме је све унапред подешено.

Други начин за генерисање XML документације је да десним кликом на пројекат одаберете Properties, па у табу Build штиклирате опцију XML documentation file. Опционо можете променити име и локацију XLM фајла који ће се генерисати.