Komentarze
Komentarze są bardzo ważne w programowaniu, używanie ich jest dobrym nawykiem, który szczególnie docenimy powracając do starego kodu po dłuższym czasie. W języku C# wyróżniamy trzy rodzaje komentarzy. Dwa z nich wyglądają dokładnie tak samo jak w języku C, a użycie ich wygląda następująco:
Ciekawą rzeczą w języku C# jest możliwość tworzenia komentarzy w formacie XML, co pozwala na automatyczne generowanie dokumentacji projektu (którą można później np. przetransformować przy pomocy języka XSL), a także ułatwia pisanie dalszych części programu, gdyż te komentarze wyświetlane są przez IntelliSense jako podpowiedzi, opisy. Użycie takich komentarzy może wyglądać następująco:
* <Summary> - Krótki opis elementu
* <Remarks> - Rozbudowany opis elementu
* <c> - Formatowanie znaków jako kodu
* <code> - Formatowanie znaków jako kodu używane w sekcji <example>
* <example> - Przykład użycia klasy lub metody
* <exception> - Wyjątki zwracane przez klasę
* <list> - Lista elementów
* <param> - Opis parametru przypisanego do funkcji
* <paramref> - Odwołanie do parametru w innym tekście
* <permission> - Zezwolenie
* <returns> - Wartość zwracana przez funkcje
* <see cref="składowa"> - Łącze do innej składowej klasy
* <seealso cref="składowa"> - Łącze w sekcji "zobacz również"
* <value> - Opis wartości właściwości
Do programu można dołączać zewnętrzne pliki dokumentacji, które będą traktowane tak jakby znajdowały się w pliku z kodem źródłowym, jest to przydatne gdy dokumentacje i kod tworzą różne osoby.
Taki komentarz pobiera przy pomocy pseudo języka Xpath sekcje member o parametrze name = "test" z sekcji doc zawartej w pliku "plik.csx":
// tak wygląda prosty komentarz
namespace Komentarze
{ // wszystko do końca tej linii jest komentarzem
class Komentarz
{
public static void Main()
{
/* użycie takiego komentarza
pozwala nam
zaznaczyć kilka linii jako komentarz*/
}
}
// obydwa rodzaje komentarza są niewidoczne dla kompilatora
}
namespace Komentarze
{ // wszystko do końca tej linii jest komentarzem
class Komentarz
{
public static void Main()
{
/* użycie takiego komentarza
pozwala nam
zaznaczyć kilka linii jako komentarz*/
}
}
// obydwa rodzaje komentarza są niewidoczne dla kompilatora
}
Dokumentacja XML
Ciekawą rzeczą w języku C# jest możliwość tworzenia komentarzy w formacie XML, co pozwala na automatyczne generowanie dokumentacji projektu (którą można później np. przetransformować przy pomocy języka XSL), a także ułatwia pisanie dalszych części programu, gdyż te komentarze wyświetlane są przez IntelliSense jako podpowiedzi, opisy. Użycie takich komentarzy może wyglądać następująco:
namespace Komentarze
{
/// <summary>
/// Opis klasy KomentarzXML
/// </summary>
public class KomentarzXML
{
/// <summary>
/// Tutaj umieszczamy opis dotyczący funkcji
/// np. funkcja zwraca dwukrotność podanej liczby
/// </summary>
/// <param name="n">tu możemy umieścić komentarz dotyczący zmiennej n</param>
/// <returns>tutaj komentarz dotyczący zwracanego typu</returns>
static int Dwukrotność(int n)
{
return n+n;
}
/// <summary>
/// Miejsce startowe aplikacji
/// </summary>
public static void Main()
{
}
}
}
{
/// <summary>
/// Opis klasy KomentarzXML
/// </summary>
public class KomentarzXML
{
/// <summary>
/// Tutaj umieszczamy opis dotyczący funkcji
/// np. funkcja zwraca dwukrotność podanej liczby
/// </summary>
/// <param name="n">tu możemy umieścić komentarz dotyczący zmiennej n</param>
/// <returns>tutaj komentarz dotyczący zwracanego typu</returns>
static int Dwukrotność(int n)
{
return n+n;
}
/// <summary>
/// Miejsce startowe aplikacji
/// </summary>
public static void Main()
{
}
}
}
Znaczniki dokumentacyjne:
* <Summary> - Krótki opis elementu
* <Remarks> - Rozbudowany opis elementu
* <c> - Formatowanie znaków jako kodu
* <code> - Formatowanie znaków jako kodu używane w sekcji <example>
* <example> - Przykład użycia klasy lub metody
* <exception> - Wyjątki zwracane przez klasę
* <list> - Lista elementów
* <param> - Opis parametru przypisanego do funkcji
* <paramref> - Odwołanie do parametru w innym tekście
* <permission> - Zezwolenie
* <returns> - Wartość zwracana przez funkcje
* <see cref="składowa"> - Łącze do innej składowej klasy
* <seealso cref="składowa"> - Łącze w sekcji "zobacz również"
* <value> - Opis wartości właściwości
Do programu można dołączać zewnętrzne pliki dokumentacji, które będą traktowane tak jakby znajdowały się w pliku z kodem źródłowym, jest to przydatne gdy dokumentacje i kod tworzą różne osoby.
/// <include fille='plik.csx' path='doc/member[@name="test"]' />
Taki komentarz pobiera przy pomocy pseudo języka Xpath sekcje member o parametrze name = "test" z sekcji doc zawartej w pliku "plik.csx":
<doc>
(...)
<member name="test">
<summary>opis</summary>
</member>
(...)
</doc>
(...)
<member name="test">
<summary>opis</summary>
</member>
(...)
</doc>
