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

Warum ist eine hochwertige Dokumentation eines C#-Projekts wichtig?

Dokumentation ist die Brücke zwischen dem Entwickler und dem Benutzer Ihres Codes. In der Welt von C# (.NET) wird diese Brücke mit XML-Kommentaren und spezialisierten Tools (DocFX, Sandcastle) gebaut. Eine gute Dokumentation:

• Beschleunigt die Einarbeitung neuer Entwickler in das Projekt
• Reduziert die Anzahl der Fragen in Chats und Tickets
• Verbessert die Codequalität (Sie refaktorieren unwillkürlich schlechte Methoden, wenn Sie dafür Doks schreiben)
• Generiert automatisch ein API-Referenzhandbuch (IntelliSense in Visual Studio)

In diesem Artikel behandeln wir den gesamten Zyklus: von der Projekteinrichtung bis zur Veröffentlichung der Dokumentation auf einer statischen Website. Alle Beispiele sind in C# (.NET 8).

1. XML-Kommentare: Grundlage der Dokumentation in C#

1.1. So aktivieren Sie die Generierung von XML-Dateien

Visual Studio (oder Rider) erstellt automatisch eine XML-Datei mit Kommentaren, wenn Sie die entsprechende Option in .csproj aktivieren:

<PropertyGroup>    <GenerateDocumentationFile>true</GenerateDocumentationFile>    <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile></PropertyGroup>

Nach dem Build erscheint im Ordner bin/Debug/net8.0/ eine XML-Datei mit Ihren Kommentaren. Diese Datei ist das Rohmaterial für DocFX und Sandcastle.

1.2. Wichtige XML-Tags

Verwenden Sie die folgenden Tags zum Schreiben der Dokumentation eines C#-Projekts:

• <summary> — Kurzbeschreibung der Klasse, Methode, Eigenschaft.
• <param name="..."> — Beschreibung des Methodenparameters.
• <returns> — Beschreibung des Rückgabewerts.
• <exception cref="..."> — Welche Ausnahmen die Methode auslösen kann.
• <example> — Anwendungsbeispiel.
• <see cref="..."> — Verweis auf einen anderen Typ oder eine andere Methode.
• <code> — Formatierter Code innerhalb der Beschreibung.

1.3. Beispiel eines vollständigen Kommentars

/// <summary>/// Führt eine sichere Division zweier Zahlen mit Nullprüfung durch./// </summary>/// <param name="dividend">Dividend (Zähler).</param>/// <param name="divisor">Divisor (Nenner). Darf nicht 0 sein.</param>/// <returns>Ergebnis der Division als Dezimalbruch.</returns>/// <exception cref="DivideByZeroException">Wird ausgelöst, wenn divisor gleich 0 ist.</exception>/// <example>/// <code>/// double result = SafeDivider.Divide(10, 3);/// Console.WriteLine(result); // 3.333.../// </code>/// </example>public static double Divide(double dividend, double divisor){    if (divisor == 0)        throw new DivideByZeroException("Division durch Null ist nicht erlaubt.");    return dividend / divisor;}

Tipp: Schreiben Sie Kommentare auf Russisch, wenn das Projekt intern ist, oder auf Englisch für eine öffentliche API. Hauptsache, Sie halten einen einheitlichen Stil ein.

2. Tools zur Dokumentationsgenerierung: DocFX vs Sandcastle

2.1. DocFX (empfohlen)

DocFX ist ein modernes Tool von Microsoft, das aus XML-Kommentaren und zusätzlichen Markdown-Dateien eine statische Website generiert. Es unterstützt C#, VB.NET und sogar JavaScript.

Installation:

dotnet tool install -g docfx

Schnellstart:

docfx init -o my-docscd my-docsdocfx builddocfx serve _site

DocFX automatisch:

• Scannt Ihre .csproj- und .sln-Dateien
• Extrahiert XML-Kommentare
• Erstellt Seiten für jede Klasse, Methode, Eigenschaft
• Fügt Navigation, Suche und schöne Themes hinzu (standardmäßig Bootstrap)