Schreiben von Dokumentation für C#-Projekte: Fortgeschrittenes Niveau

Einleitung: Warum Dokumentation Code ist und kein Anhängsel

In der professionellen Entwicklung mit C# (.NET) wird das Schreiben von Dokumentation oft als Routineaufgabe angesehen, die aufgeschoben wird. Auf fortgeschrittenem Niveau ist Dokumentation jedoch nicht mehr nur ein Kommentar – sie wird Teil der Projektarchitektur, ein Werkzeug zur Generierung von API-Referenzen, zur Integration in die IDE und zur Automatisierung von Tests.

In diesem Artikel betrachten wir, wie man qualitativ hochwertige technische Dokumentation für C#-Projekte erstellt, unter Verwendung moderner Werkzeuge und Best Practices. Sie erfahren, wie Sie Kommentare in ein vollwertiges Referenzsystem verwandeln, das sowohl für Entwickler als auch für Benutzer Ihrer API nützlich ist.

1. XML-Kommentare: Vom Basis- zum Fortgeschrittenenniveau

Fortgeschrittene Dokumentation beginnt mit der korrekten Verwendung von XML-Kommentaren. In C# werden sie auf Compiler-Ebene unterstützt und ermöglichen die Generierung von Dokumentation im XML-Format, das dann in HTML, PDF oder andere Formate umgewandelt werden kann.

1.1. Strukturierung komplexer Typen

Für große Projekte ist es wichtig, nicht nur Methoden zu dokumentieren, sondern auch verschachtelte Typen, Überladungen und Generics. Verwenden Sie die Tags <typeparam>, <typeparamref> und <see>, um Querverweise zu erstellen.

/// <summary>\n/// Stellt ein universelles Repository für die Arbeit mit Entitäten dar.\n/// </summary>\n/// <typeparam name="TEntity">Der Entitätstyp, muss <see cref="IEntity"/> implementieren.</typeparam>\n/// <typeparam name="TKey">Der Schlüsseltyp der Entität (int, Guid, string).</typeparam>\npublic class Repository<TEntity, TKey> : IRepository<TEntity, TKey>\n    where TEntity : class, IEntity<TKey>\n{\n    /// <summary>\n    /// Ruft eine Entität anhand ihrer ID ab.\n    /// </summary>\n    /// <param name="id">Die ID der Entität.</param>\n    /// <returns>Die Entität vom Typ <typeparamref name="TEntity"/> oder null.</returns>\n    /// <exception cref="ArgumentNullException">Wird ausgelöst, wenn id null ist.</exception>\n    public async Task<TEntity?> GetByIdAsync(TKey id)\n    {\n        // Implementierung\n    }\n}\n

1.2. Dokumentation von Ausnahmen und Vorbedingungen

Fortgeschrittene Dokumentation sollte alle möglichen Ausnahmen und Vorbedingungen explizit beschreiben. Verwenden Sie das Tag <exception> für jeden Ausnahmetyp.

/// <summary>\n/// Führt die Validierung und Speicherung einer Bestellung durch.\n/// </summary>\n/// <param name="order">Das Bestellungsobjekt.</param>\n/// <exception cref="ArgumentNullException">Wenn order null ist.</exception>\n/// <exception cref="ValidationException">Wenn das Bestellmodell ungültig ist.</exception>\n/// <exception cref="DbUpdateException">Wenn ein Fehler beim Speichern in der Datenbank auftritt.</exception>\npublic async Task SaveOrderAsync(Order order)\n{\n    // Implementierung\n}\n

1.3. Verwendung von <inheritdoc> zur Vermeidung von Duplikaten

Bei der Implementierung von Schnittstellen oder dem Überschreiben virtueller Methoden verwenden Sie <inheritdoc>, um die Dokumentation automatisch vom Basistyp zu erben. Das spart Zeit und gewährleistet Konsistenz.

public interface IDataService\n{\n    /// <summary>\n    /// Lädt Daten von der angegebenen URL.\n    /// </summary>\n    Task<string> LoadDataAsync(string url);\n}\n\npublic class HttpDataService : IDataService\n{\n    /// <inheritdoc />\n    public async Task<string> LoadDataAsync(string url)\n    {\n        // Implementierung\n    }\n}\n

2. Werkzeuge zur Dokumentationsgenerierung: DocFX und Sandcastle

Um XML-Kommentare in eine vollwertige Dokumentationswebsite zu verwandeln, verwenden Sie spezialisierte Werkzeuge. Betrachten wir die zwei wichtigsten