TOC

This article is currently in the process of being translated into Polish (~65% done).

Podstawy:

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ń

If you're using Visual Studio, you can actually get some help tracking your code comments. In the Task List window (access it from the menu View > Task List) your comments will appear if they use the special, but very simple Task List comment syntax:

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

So if the single-line comment is immediately followed by TODO or HACK, it will appear in the Task List of Visual Studio, like this:

And there are more types - depending on the version of Visual Studio you're using, it will respond to some or all of the following comment tokens:

  • TODO
  • HACK
  • NOTE
  • UNDONE

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

Podsumowanie

Code comments are extremely useful in documenting your code or for the purpose of leaving clues to your self or your potential colleagues on how stuff works. As an added benefit, they're great when you need to test something quickly - just copy a line and comment out the original line and you can see how it works now. If you're not happy with the result, you can just delete the new line and uncomment the original line and you're back to where you started.

And don't worry about the end-user snooping through your comments - they are, as already mentioned, completely ignored by the compiler and therefore not in anyway included in your final DLL or EXE file. Code comments are your personal free-space when programming, so use it in any way you want to.

This article has been fully translated into the following languages: Is your preferred language not on the list? Click here to help us translate this article into your language!