Dokumentation in C#: Wie man Code schreibt, der für sich selbst spricht

Dokumentation in C#-Projekten: Die Kunst, mit dem zukünftigen Ich zu sprechen

Seien wir ehrlich: Wer von uns hat nicht schon Code verflucht, den er vor einem halben Jahr geschrieben hat? "Was zum Teufel, warum heißt diese Eigenschaft CustomerID, gibt aber OrderId zurück?" – fragen wir uns, während wir durch die Seiten eines fremden (oder eigenen) Projekts blättern. In der Welt von C# ist dieses Problem besonders akut, weil die Sprache leistungsstark, das Ökosystem riesig und die Zeit für Analysen immer knapp ist.

Eine gute Dokumentation in C# ist keine langweilige Pflicht, sondern eine Superkraft, die Stunden des Debuggens und Nerven spart. In diesem Artikel zeige ich Ihnen, wie Sie Ihren Code in eine transparente, verständliche Geschichte verwandeln, indem Sie die Best Practices für die Dokumentation in .NET anwenden. Los geht's!

Warum XML-Kommentare Ihr neuer bester Freund sind

In C# ist die Dokumentation direkt in die Syntax integriert. Sie schreiben XML-Kommentare in C# direkt vor die Deklaration einer Klasse, Methode oder Eigenschaft, und die Entwicklungsumgebung (Visual Studio, Rider) übernimmt sie automatisch. Das ist nicht nur schön – es ist funktional.

Stellen Sie sich vor, Sie sind ein Entwickler, der nach einem Jahr zu einem Projekt zurückkehrt. Sie sehen eine Methode:

public int Process(byte[] data, int offset, int length)\n{\n    // 200 Zeilen Magie...\n}

Was macht data? Und offset – ist das der Anfang oder das Ende? Ohne Code-Dokumentation ist das ein Rätsel. Stellen Sie sich nun vor, Sie sehen stattdessen:

/// <summary>\n/// Verarbeitet einen eingehenden Datenstrom und berechnet eine Prüfsumme.\n/// </summary>\n/// <param name="data">Das Byte-Array mit den Rohdaten.</param>\n/// <param name="offset">Der Offset vom Anfang des Arrays, ab dem die Verarbeitung beginnt.</param>\n/// <param name="length">Die Anzahl der zu verarbeitenden Bytes.</param>\n/// <returns>Die Prüfsumme als 32-Bit-Ganzzahl.</returns>\npublic int Process(byte[] data, int offset, int length)\n{\n    // ...\n}

Das ist bereits ein Krimi mit Antworten. Die Best Practices für die Dokumentation bestehen genau in dieser Klarheit: Jeder Parameter, jede Ausnahme, jeder Rückgabewert sollte erklärt werden.

Die wichtigsten XML-Dokumentationstags

\n
• <summary> – Kurzbeschreibung der Methode, Klasse oder Eigenschaft. Obligatorisch für öffentliche Member.
\n
• <param> – Beschreibung jedes Parameters. Verwenden Sie das Attribut name.
\n
• <returns> – Was die Methode zurückgibt. Auch wenn die Methode void zurückgibt, geben Sie an, ob sie den Zustand ändert.
\n
• <exception> – Welche Ausnahmen die Methode werfen kann. Das ist eine Rettung für diejenigen, die Ihre API verwenden.
\n
• <example> – Ein Anwendungsbeispiel. Einmal sehen ist besser als hundertmal lesen.
\n
• <remarks> – Zusätzliche Anmerkungen, die nicht in die Zusammenfassung passen.
\n

Ein Beispiel für eine vollständige C# XML-Dokumentation für eine Klasse:

/// <summary>\n/// Stellt einen Systembenutzer mit Basisinformationen dar.\n/// </summary>\n/// <remarks>\n/// Diese Klasse ist nicht threadsicher. Verwenden Sie für den Multithread-Zugriff <see cref="UserService"/>.\n/// </remarks>\npublic class User\n{\n    /// <summary>\n    /// Die eindeutige Benutzerkennung (GUID).\n    /// </summary>\n    public Guid Id { get; set; }\n\n    /// <summary>\n    /// Die E-Mail-Adresse des Benutzers. Muss im System eindeutig sein.\n    /// </summary>\n    /// <exception cref="ArgumentException">Wird ausgelöst, wenn die E-Mail ein ungültiges Format hat.</exception>\n    public string Email { get; set; }\n}

Beachten Sie das Tag <see