Schreiben von Dokumentation für ein C#-Projekt: von A bis Z

Schreiben von Dokumentation für ein C#-Projekt: von A bis Z

Qualitativ hochwertige Dokumentation ist der Schlüssel zu einem erfolgreichen und wartbaren C#-Projekt. Sie hilft Entwicklern, sich schnell in den Code einzuarbeiten, erleichtert das Onboarding neuer Teammitglieder und reduziert die Anzahl der Fehler. In diesem Artikel werden wir den gesamten Prozess der Erstellung von Dokumentation für ein C# (.NET)-Projekt durchgehen: von den Grundlagen der XML-Kommentare bis zur automatischen Generierung ansprechender Websites.

1. Grundlagen der XML-Kommentare in C#

Die Standardmethode zur Dokumentation von Code in C# sind XML-Kommentare. Sie werden vor der Deklaration einer Klasse, Methode, Eigenschaft oder eines anderen Elements geschrieben und beginnen mit drei Schrägstrichen ///. Der C#-Compiler erkennt diese Kommentare und kann eine XML-Dokumentationsdatei generieren.

Hier sind die grundlegenden Tags, die Sie am häufigsten verwenden werden:

\n
• <summary> — Kurzbeschreibung des Elements.
\n
• <param name="Name"> — Beschreibung des Methodenparameters.
\n
• <returns> — Beschreibung des Rückgabewerts.
\n
• <exception cref="Typ"> — Beschreibung der Ausnahme, die die Methode auslösen kann.
\n
• <example> — Anwendungsbeispiel.
\n
• <remarks> — Zusätzliche Anmerkungen.
\n

Beispiel für einen korrekten XML-Kommentar für eine Methode:

/// <summary>\n/// Berechnet die Fakultät einer nicht negativen ganzen Zahl.\n/// </summary>\n/// <param name="n">Nicht negative ganze Zahl.</param>\n/// <returns>Die Fakultät der Zahl n.</returns>\n/// <exception cref="System.ArgumentException">Wird ausgelöst, wenn n kleiner als 0 ist.</exception>\n/// <example>\n/// <code>\n/// int result = Factorial(5);\n/// // result ist gleich 120\n/// </code>\n/// </example>\npublic static int Factorial(int n)\n{\n    if (n < 0)\n        throw new ArgumentException("n darf nicht negativ sein", nameof(n));\n\n    int result = 1;\n    for (int i = 1; i <= n; i++)\n    {\n        result *= i;\n    }\n    return result;\n}

2. Dokumentieren von Klassen und Eigenschaften

Vergessen Sie nicht, nicht nur Methoden, sondern auch die Klassen selbst sowie deren Eigenschaften und Felder zu dokumentieren. Dies ist besonders wichtig für öffentliche APIs, die von anderen Entwicklern verwendet werden.

Verwenden Sie für Eigenschaften die Tags <summary> und <value> (zur Beschreibung des gespeicherten Werts):

/// <summary>\n/// Stellt einen Systembenutzer dar.\n/// </summary>\npublic class User\n{\n    /// <summary>\n    /// Eindeutige Benutzerkennung.\n    /// </value>\n    public int Id { get; set; }\n\n    /// <summary>\n    /// Vollständiger Name des Benutzers.\n    /// </summary>\n    /// <value>Zeichenfolge, die Vor- und Nachnamen enthält.</value>\n    public string FullName { get; set; }\n\n    /// <summary>\n    /// Erstellt einen neuen Benutzer.\n    /// </summary>\n    /// <param name="id">Kennung.</param>\n    /// <param name="fullName">Vollständiger Name.</param>\n    public User(int id, string fullName)\n    {\n        Id = id;\n        FullName = fullName ?? throw new ArgumentNullException(nameof(fullName));\n    }\n}

3. Generieren der XML-Datei und Erstellen der Dokumentation

Um eine XML-Datei aus Ihren Kommentaren zu erhalten, müssen Sie das Projekt konfigurieren. Fügen Sie in Visual Studio oder über die Datei .csproj Folgendes hinzu:

<PropertyGroup>\n  <GenerateDocumentationFile>true</GenerateDocumentationFile>\n  <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile>\n  <NoWarn>$(NoWarn);1591</NoWarn> <!-- Deaktiviert die Warnung zu fehlenden Kommentaren, falls gewünscht -->\n</PropertyGroup>

Nach dem Erstellen des Projekts erhalten Sie eine XML-Datei, die zur Erstellung einer schönen