C#

Komentarze

pRoGi

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
* <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>
C#

0 komentarzy