Komentarze

Programując, szybko zorientujesz się, że każdy znak i wyraz jaki zapiszesz będzie miał specjalne znaczenie. W C#, zauważysz wiele słów kluczowych takich jak class, namespace, public i wiele innych. Zauważysz również, że kompilator upewni się, czy prawidłowo ich używasz, tak samo jak własnych zmiennych i metod. C# jest rygorystycznym językiem, lecz kompilator zrobi wszystko by pomóc ci wprowadzić je poprawnie. Mimo wszystko, masz jednak możliwość pisania czegokolwiek tylko chcesz, dzięki komentarzom.

Pewnie widziałeś już komentarze w kodzie. W C# tak jak w każdym innym języku programowania koncept komentarzy jest wiecznie uniwersalny. Mimo wszystko, sposób w jaki są zapisywane mocno się różni, spójrzmy na typy komentarzy, które można zastosować w kodzie.

Komentarze jednoliniowe

Najprostszym typem komentarzy w C# jest komentarz jednoliniowy. Jak sama nazwa wskazuje, zamienia jeden wers (linijkę) tekstu w komentarz - zobaczmy jak to może wyglądać:

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

To takie proste: Poprzedź linię kodu dwoma prawymi ukośnikami (//), a kompiler przestanie sprawdzac to, co zostało napisanę. Dotyczy to tylko linii kodu poprzedzonej ukośnikami, co więcej, możesz użyć znaku komentarza wielokrotnie w różnych liniach kodu.W ten sposób, używając jedno-liniowego komentarza by skomentować kilka linii kodu

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

Komentarze wieloliniowe

W przypadku, w którym chcielibyśmy napisać wiele linijek komentarzy, rozsądniej jest użyć wielo-liniowego wariantu, który oferuje nam C#. Zamiast rozpoczynania każdej pojedynczej linijki prefiksem pokazanym powyżej, wystarczy użyć ciągu znaków rozpoczynających i zamykających. Wszystko pomiędzy będzie traktowane jako komentarz.

/*  
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  
{
    ......

Użyj inicjatora komentarza w postaci prawego ukośnika i gwazdki (/*), W ten sposób nie istotne czy napiszesz jedną, czy wiele linii kodu, kompilator zawsze zignoruje tekst, do momentu zakończenia komentarza znakiem gwiazdki i prawgo ukośnika (*/).

Tak jak prawie z każdym aspektem programowania tak i z komentarzami w C#, debatuje się, których komentarzy powinno się używać: jedno-liniowych (//) czy blokowych (/*) (*/). Osobiście używam obydwu kometarzy w zależności od potrzeby wynikającej z sytuacji! To zależy wyłącznie od Ciebie, którego z nich użyjesz!

Dokumentacje

Komentarze w dokumentacji (czasami opisywane jako komentarze dokumentacji XML). Wyglądają jak regularne, tylko są osadzone w XML. Tak jak regularne komentarze występują w dwóch formach: Pojedyńczego komentarza i blokowego. Zapisuje się je podobnie z małym wyjątkiem w postaci dodatkowego znaku. Dla komentarza liniowego będą to trzy prawe ukośniki (///) zamiast dwóch. Dla komentarza blokowego dodaję się dodatkową gwiazdkę przy inicjatorze komentarza (/**). Zobaczmy jak to wygląda:

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; }
}

Tutaj widzisz dwa warianty. Skutek użycia każdego z nich jest identyczny, jednak w dokumentacji skłania się ku używaniu komentarza jedno-liniowego.

Dokumentowanie kodu komentarzami dekumentacji to spory temat. Jednak bez obaw, omówimy to zagadnienie dokładniej w późniejszym artykule. Teraz wiesz jak wyglądają!

Komentarze i listy zadań

Jeżeli używasz Visual Studio, możesz uzyskać dostęp do swoich komentarzy. W oknie Listy Zadań (dostaniesz się tam poprzez Widok > Lista Zadań) Twoje komentarze pojawią się, jeżeli użyłeś specjalnej lecz bardzo prostej składni Listy Zadań:

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

Więc jeżeli zaraz po jedno-liniowym komentarzu użyjesz TODO albo HACK, pojawi się on w Liście Zadań programu Visual Studio, tak jak poniżej:

Jest więcej typów - w zależności od wersji Visual Studio której używasz, będziesz mógł użyć kilku lub wszystkich tokenów komentarzy:

• TODO
• HACK
• NOTE
• UNDONE

Jeśli chcesz, możesz nawet dodać swoje własne znaczniki – wystarczy tylko wykonać kroki opisane w tym artykule.

Podsumowanie

Komentowanie kodu jest bardzo pomocne przy dokumentowaniu kodu lub po to aby zostawić sobie lub potencjalnym współpracownikom informację o tym co jak działa. Jako dodatkowa korzyść, komentarze są pomocne gdy musisz coś szybko przetestować. Po prostu wpisujesz lub wklejasz kod to testu, stary kod otaczasz komentarzem i możesz sprawdzić jak działa nowe rozwiązanie. Jeśli wynik nie jest zadowalający, zawsze możesz usunąć nowe linijki kodu i usunąć komentarz ze starego kodu aby przywrócić go do pierwotnego stanu.

I nie przejmuj się, że użytkownik aplikacji będzie mógł później czytać Twoje komentarze. Są one całkowicie ignorowane przez kompilator i nie są dołączane do pliku DLL lub EXE. Komentarze w kodzie są Twoją bezpieczną przestrzenią w kodzie, więc używaj jej tak jak chcesz.