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:

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

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()
		{
		}
	}
}

Znaczniki dokumentacyjne:

``` * <summary> - Krótki opis elementu * <remarks> - Rozbudowany opis elementu * <c> - Formatowanie znaków jako kodu * - 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>