Może być ciężko Wam uwierzyć, że można z tak prostej rzeczy zrobić wykład jednak mam ku temu powód. Komentarze w języku C# mają nieco większe pole do popisu niż w większości innych języków. Oprócz konkretów, wtrącę także szczyptę teorii po co się to w ogóle stosuje, choć na pewno już słyszeliście o zastosowaniu. Nawet jeśli nie, i tak łatwo się go domyślić.

POZNAJ TRZY RÓŻNE KOMENTARZE W JĘZYKU C#!

Tak, dobrze przeczytaliście. TRZY, nie dwa! Choć niektórym z Was mogą być znane dwa rodzaje komentarzy dostępnych w prawie każdym języku programowania, to na tym świat się nie kończy i twórcy "CSharpa" postanowili dać coś od siebie.

KAPKA TEORII

Komentarze mają na celu pozostawienie swoistej notatki dla siebie i dla innych, pisanej w języku naturalnym po co coś jest, co to ma robić, po co ma istnieć i tak dalej. Przy użyciu obowiązującej symboliki, sprawiamy że dana linijka kodu (albo wiele linijek) zostanie zignorowana przez kompilator i nie będzie traktowana jak instrukcja (lub instrukcje). Choć zostawianie komentarzy przez programistów jest dość często uprawianą praktyką (w niejednej książce znajdziecie tekst, żebyście używali ich jak najwięcej), ja w swoich kodach źródłowych ich nie używam i staram się pisać instrukcje w taki sposób, aby nie wymagały żadnego komentarza. Da się tak pisać! To tylko mała dygresja i opinia.

TRZY RODZAJE KOMENTARZY

Obowiązują trzy "typy" lub "rodzaje" komentarzy w języku C#. Oto one:

KOMENTARZ LINIOWY

Najprostszy rodzaj komentarza jaki można wstawić. Kombinacja znaków "//" (dwa ukośniki bez spacji) tworzy komentarz liniowy. Wywołuje to taki efekt, że zaraz po dwóch ukośnikach, możemy pisać co chcemy i nie zostanie to uwzględnione przez kompilator. Możecie wstawić tam jakieś zdanie, niecenzuralne słowo lub cokolwiek innego. Nie wpłynie to na kompilację, zatem nie będzie to traktowane jak błąd składniowy.

// komentarz liniowy (wiersz nie będzie brany pod uwagę przez kompilator)

Miejcie z tyłu głowy, że to ma wpływ tylko na dany wiersz! Gdybyście chcieli umieścić dowolny tekst w kilku wierszach naraz, wtedy komentarz liniowy nie wystarczy i trzeba sięgnąć po...

KOMENTARZ BLOKOWY (WIELOWIERSZOWY)

Blokowe komentarze w języku C# (nazywane także wielowierszowymi), jak sama nazwa wskazuje, to wstawianie komentarzy wymagających więcej niż jednej linii (choć nadal można potrzebować tylko jednej). Tworzycie go wstawiając charakterystyczne znaczniki po obu stronach. Początek zaczyna się od kombinacji "/*" (ukośnik i asterysk), a koniec oznaczacie odwrotnie, "*/" (asterysk i ukośnik). To spowoduje możliwość wstawienia jakiegokolwiek tekstu pomiędzy tymi znacznikami, nawet kiedy umieszczone są w różnych wierszach kodu. Na przykład, jeśli znaczniki dzieli pięć wierszy, to pięć pełnych wierszy macie do dyspozycji.

/*
Komentarz
blokowy
zajmuje
pięć
wierszy!
*/

Uważajcie tylko na zagnieżdżanie komentarzy blokowych, gdyż jest to niemożliwe! Chodzi mi o to, że pod żadnym pozorem nie wolno Wam wstawić nowej pary znaczników wewnątrz istniejącej:

/*
Komentarz blokowy.
/* Spróbuję zagnieździć */	// błąd
*/

Kompilator wpadnie w degrengoladę i nie będzie wiedział który "koniec" uważać za ten prawdziwy! Można natomiast wstawić wewnątrz komentarz liniowy.

Jednak...na tym komentarze w języku C# się nie kończą! Jest jeszcze jeden typ.

KOMENTARZ XML

To jest trzeci wariant niewystępujący w każdym języku wysokiego poziomu, przeznaczony do tworzenia znaczników XML ("eXtensible Markup Language"). Robi się go bardzo podobnie do pierwszego, tylko teraz dajemy trzy ukośniki pod rząd, zamiast dwóch ("///"). Sama kombinacja nic nie daje. Wewnątrz komentarza XML, człowiek może umieszczać znaczniki charakterystyczne dla XML, czyli w taki sposób:

/// <summary>
/// Klasa <c>Program</c> to klasa, od której rozpoczyna się każdy program w języku C#.
/// <para>
/// <see href="https://jasonxiii.pl">Naucz się języka C# u Jasona!</see>
/// </para>
/// </summary>

Składnia lekko "pachnąca" HTML'em. Takie znaczniki powinny znajdować się nad nagłówkiem klasy, metody albo innej konstrukcji tego typu. Zostaje jeszcze do wyjaśnienia po co mielibyśmy się wysilać przy tym? To się przydaje podczas generowania dokumentacji w języku XML, a także wyskakujących "chmurek", czyli podpowiedzi co "to coś" robi albo po co jest, albo jaką wartość zwraca. Te "chmurki" widać w "Visual Studio" i pojawiają się w chwili, kiedy jest w stanie podpowiedzieć nam autouzupełnianiem co zaznaczona kursorem myszy konstrukcja potrafi.

Opis klasy po najechaniu na jej nazwę w "Visual Studio 2019"

Opis klasy w "Visual Studio 2019" po najechaniu na jej nazwę (po wstawieniu nad nagłówkiem klasy powyższych znaczników).

Występuje szereg znaczników "XML'owych", a komentarze w języku C# wspierają je wszystkie. Oto tabela (każdy znacznik kończy się takim samym ze znakiem ukośnika przed nazwą, jak w HTML!):

Znacznik Znaczenie
<c> oznaczenie fragmentu komentarza w postaci kodu
<code> oznaczenie wielu wierszy fragmentu komentarza w postaci kodu
<example> oznaczenie przykładowego użycia fragmentu kodu
<exception> odniesienie do wyjątku
<include> odniesienie do pliku zewnętrznego dołączanego do dokumentacji
<list> wyliczenie w postaci listy
<para> akapit tekstu
<param> opis parametru metody
<paramref> odniesienie słowa w opisie do parametru
<permission> opis dostępu do składowej (np. danej składowej lub metody)
<remarks> opis składowej (np. danej składowej lub metody)
<returns> opis zwracanej wartości
<see> odnośnik do określonego miejsca w dokumentacji
<seealso>
<summary> opis typu lub składowej (działa tak samo, jakbyśmy wstawiali komentarze w języku C#)
<typeparam> opis typu generycznego
<typeparamref> informacje na temat typu generycznego
<value> opis właściwości (pola czyli danej składowej)

Nie próbujcie tego wkuwać. Po to wymyślono dokumentację. Wystarczy Wam wiedza po co się to stosuje, jak się pisze i jak to nazwać. A ponieważ jest tego od groma (to nie są wszystkie znaczniki jakie występują), nie sposób opisać wszystkiego ze szczegółami i zdjęciami.

Komentarze w języku C#

W języku C# występują trzy rodzaje komentarzy: liniowy, blokowy oraz XML do tworzenia dokumentacji w języku XML.


Wszystko na ten temat. Jak widzicie, komentarze w języku C# to nie tylko liniowy i blokowy, ale także rzadziej spotykany przystosowany pod składnię XML dla generowania dokumentacji. Warto wiedzieć, że istnieje coś takiego.

PODOBNE ARTYKUŁY