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

Warum Dokumentation eine Superkraft für Entwickler ist

Stellen Sie sich vor: Sie öffnen ein fremdes Swift-Projekt ein halbes Jahr nachdem es geschrieben wurde. Der Code funktioniert, aber zu verstehen, warum der Autor es genau so und nicht anders gemacht hat – unmöglich. Keine Kommentare, Variablennamen im Stil von a1, temp2. Kommt Ihnen das bekannt vor?

Gute Dokumentation ist nicht nur Höflichkeit gegenüber dem zukünftigen Ich. Sie ist ein Werkzeug, das Stunden des Debuggings spart, das Onboarding neuer Entwickler beschleunigt und Chaos in ein geordnetes System verwandelt. In diesem Artikel behandeln wir die besten Praktiken zur Dokumentation von Swift-Code, von grundlegenden Kommentaren bis hin zu fortgeschrittenem DocC.

Grundlagen: Von einfachen Kommentaren zu aussagekräftigen Beschreibungen

//, /// und /* */ – wann was verwenden

In Swift gibt es drei Arten von Kommentaren, und jeder hat seine Aufgabe:

• Einzeilige // – für schnelle Notizen, TODOs oder temporäres Deaktivieren von Code. Übertreiben Sie es nicht: Wenn ein Kommentar Offensichtliches erklärt, ist er überflüssig.
• Mehrzeilige /* */ – für Erklärungsblöcke oder zum Deaktivieren ganzer Codeabschnitte beim Debuggen.
• Dokumentierende /// – das ist Ihr Hauptwerkzeug. Xcode übernimmt sie automatisch und zeigt sie in der Quick Help an.

/// Berechnet die Fläche eines Kreises anhand des Radius./// - Parameter radius: Der Radius des Kreises in Metern./// - Returns: Die Fläche in Quadratmetern./// - Throws: `InvalidInputError.negativeRadius`, wenn radius < 0.func areaOfCircle(radius: Double) throws -> Double {    guard radius >= 0 else {        throw InvalidInputError.negativeRadius    }    return Double.pi * radius * radius}

Schlechter vs. guter Kommentar

Vergleichen Sie die beiden Ansätze:

// SCHLECHT: Offensichtlicher Kommentar// Erhöht den Zähler um 1counter += 1

// GUT: Erklärt das "Warum"// Verwenden Inkrement, weil dies ein kritischer// Performance-Bereich ist und die ++-Operation in Swift veraltet istcounter += 1

Goldene Regel: Ein Kommentar sollte die Frage „Warum“ beantworten, nicht „Was“ der Code tut. Der Code selbst sollte lesbar sein, damit das „Was“ ohne Worte verständlich ist.

DocC – Dokumentation der nächsten Generation

Was ist DocC und warum ist es ein Must-have

Mit dem Erscheinen von Xcode 13 hat Apple DocC (Documentation Compiler) vorgestellt – ein Werkzeug, das Ihre ///-Kommentare in eine schöne, interaktive Dokumentation direkt in Xcode und im Web verwandelt. Schluss mit PDF-Dateien und Wiki-Seiten, die innerhalb einer Woche veralten.

Wie man DocC in einem Projekt verwendet

1. Einrichtung: Wählen Sie in Xcode Product → Build Documentation. DocC sammelt automatisch alle dokumentierten Symbole.
2. Links innerhalb der Dokumentation: Verwenden Sie `` für Verweise auf andere Typen:

/// Verwenden Sie ``NetworkManager`` zum Senden von Anfragen./// Weitere Details im Artikel <doc:NetworkGuide>.

3. Markdown-Funktionen: DocC unterstützt Überschriften, Listen, Tabellen, Bilder und sogar Diagramme mit Mermaid:

/// # Arbeitsablauf/// 1. Cache prüfen/// 2. Wenn nicht vorhanden – Anfrage an den Server/// 3. Ergebnis speichern

Dokumentation für ein ganzes Modul erstellen

Fügen Sie eine Datei Documentation.docc im Stammverzeichnis des Projekts hinzu. Im Inneren – eine Struktur in Markdown:

// MyFramework.docc/MyFramework.md# ``MyFramework``

Asynchrone Bibliothek für die Netzwerkarbeit.

## Topics

### Hauptkomponenten- ``NetworkManager``- ``RequestBuilder``

### Erweiterungen- <doc:CustomizingRequests>

Fortgeschrittene Techniken: Dokumentation schreiben, die gelesen wird

Nach Rollen strukturieren

Nicht jeder Code erfordert die gleiche Detailtiefe. Teilen Sie die Doku