Wenn Projekte eine gewisse Größe erreichen oder von anderen Entwicklern genutzt werden sollen, ist es doch immer hilfreich zu sehen was eine Methode, eine Klasse, eine Struktur oder Ähnliches zu einem bestimmten Zeitpunkt genau macht. Aber wie stellt man dies am Besten an? Der erste Schritt hierhin sind sicherlich gut durchdachte „Coding Styles“ an denen sich die Entwickler halten sollten, um so einheitlichen Code zu erschaffen. Aber es gibt da noch einen sehr effektiven Weg den Quellcode mehr als gut zu dokumentieren, die sogenannten Summary-Kommentare. Diese bieten gegenüber normalen Kommentaren zwei Vorteile: 1. Sie sind durch die Visual Studio Intellisense zu sehen. 2. Mithilfe dieser Kommentare und einem zusätzlichen Tool kann eine „Compiled HTML“-Datei (kurz: CHM) erzeugt werden.
Aufgebaut sind diese Kommentare wie normales XML. Hierbei gibt es eine Reihe vordefinierter Tags, es können aber auch eigene genutzt werden. Für den Fall, dass der „Sandcastle Help File Builder“ (siehe: http://www.codeproject.com/Articles/15176/Sandcastle-Help-File-Builder) genutzt wird, um diese Dokumentationsdateien zu erzeugen, können auch andere Quelltexte wie Examples und UnitTests über diese Summary-Kommentare verlinkt werden. Angelegt werden Summary-Kommentare über Methoden, Funktionen, Eigenschaften, Events, Delegates, Klassen, Strukturen sowie Enumerationen. Aber wie sieht so ein Kommentar aus?
So ein Kommentar an sich hat eine sehr simple Struktur. Sehen wir uns diese doch einfach einmal an einem schon „komplexen“ Beispiel an:
/// <summary>
/// Dieser Text wird von der Intellisense angezeigt und dient quasi als Kurzbeschreibung.
/// </summary>
/// <param name="NameDesErstenParameters">Hier wird der erste Parameter erklärt.</param>
/// <param name="NameDesZweiterParameters">Hier wird der zweite Parameter erklärt.</param>
/// <returns>
/// Hier wird erklärt was die Methode als Ergebnis liefert. <br />
/// Hierfür können unter anderem auch Tabellen verwendet werden:
/// <list type="table">
/// <listheader>
/// <term>Überschrift des Terms</term>
/// <description>Überschrift der Beschreibung</description>
/// </listheader>
/// <item>
/// <term>Wenn X eintritt.</term>
/// <description>X kann nur eintreten, wenn A.</description>
/// </item>
/// <item>
/// <term>Wenn Y eintritt.</term>
/// <description>Y kann nur eintreten, wenn B.</description>
/// </item>
/// <item>
/// <term>Wenn Z eintritt.</term>
/// <description>Z kann nur eintreten, wenn C.</description>
/// </item>
/// </list>
/// </returns>
/// <exception cref="TypDerMöglichenException">Tritt ein, wenn ABC.</exception>
/// <remarks>
/// Zusätzliche Kommentare, die nur in einer automatisch erzeugten Dokumentation auftauchen. <br />
/// - Hier kann auch eine Aufzählung stattfinden. <br />
/// - Hier kann auch eine Aufzählung stattfinden. <br />
/// Auch können mittels "<see cref="HierZuVerlinkenderTyp" /> Verlinkungen auf andere Klassen, Typen, Enumerationen, etc. eingefügt werden. <br />
/// Mittels "<see cref="NameDerMethode(TypDesErstenParameters, TypDesZweitenParameters)" /> Verlinkungen auf andere Methoden erfolgen. <br />
/// Die Verlinkung auf einen generischen Typen würde so aussehen: <see cref="GenerischerTyp{TData}" />
/// </remarks>
/// <example>
/// In diesem Tag kann eine Verlinkung auf eine andere Quellcode Datei (z.B. ein UnitTest) erfolgen, der in der Dokumentaiton zur Erklärung dient.
/// <code source="RelativerPfadZurDatei.cs" lang="CSharp" />
/// <code source="RelativerPfadZurDatei.vb" lang="VB.NET" />
/// <code source="RelativerPfadZurDatei.xaml" lang="XAML" />
/// </example>
/// <CreatedOn>05.09.2012 11:50</CreatedOn>
/// <CreatedBy>Sebastian Kruse</CreatedBy>
Die hier in den Tags eingesetzten Texte sind dabei auch zugleich die Erklärungen. Im Verhältnis hat man hierdurch einen geringen Aufwand für viel Leistung. Hierbei können normale HTML-Tags für die zusätzliche Verferinerung genutzt werden. Auch das Einbinden von Bildern im „Sandcastle Help File Builder“ ist kein Problem. Weitere Informationen zu Summary-Kommentaren können der MSDN (siehe: http://msdn.microsoft.com/de-de/library/vstudio/2d6dt3kf.aspx) entnommen werden.