Dokumentation in Kotlin: Code schreiben, der für sich selbst spricht

Dokumentation in Kotlin-Projekten: Die Kunst, verstanden zu werden

Stellen Sie sich vor: Sie öffnen ein fremdes Kotlin-Projekt. Der Code ist schön, prägnant, aber... Sie verstehen nicht, wozu diese Funktion dient und was sie zurückgibt. Kommt Ihnen bekannt vor? Und jetzt stellen Sie sich vor, dieses Projekt wäre Ihr eigenes, aber ein halbes Jahr später. Dokumentation in Kotlin ist nicht nur Höflichkeit gegenüber Kollegen. Es ist eine Investition in die Zukunft Ihres Codes.

In diesem Artikel analysieren wir die besten Praktiken zur Dokumentation von Kotlin-Projekten. Sie erfahren, wie Sie KDoc, Dokka und Plain-Kommentare so einsetzen, dass Ihr Code für sich selbst spricht. Los geht's!

Warum ist Dokumentation in Kotlin nicht langweilig?

Kotlin ist eine Sprache, die für Menschen entwickelt wurde. Sie liest sich wie Englisch und ihre Syntax befreit von Boilerplate-Code. Aber selbst der eleganteste Code kann ohne Dokumentation ein Rätsel sein. Besonders wenn es um Folgendes geht:

\n
• Komplexe Geschäftslogiken;
\n
• Bibliotheken und APIs, die von anderen Entwicklern genutzt werden;
\n
• Android-Projekte mit einem langen Lebenszyklus;
\n
• Unternehmenslösungen, bei denen Personalfluktuation normal ist.
\n

Eine gute Kotlin-Dokumentation löst drei Aufgaben: Sie erklärt „was“ der Code tut, „warum“ er es tut und „wie“ man ihn verwendet. Ohne sie riskieren Sie Code, den niemand anfassen möchte (nicht einmal Sie selbst).

KDoc: Das wichtigste Werkzeug zur Dokumentation von Kotlin

KDoc ist das Pendant zu JavaDoc für Kotlin. Es verwendet Kommentare der Form /** ... */ und unterstützt Markdown. Es ist der De-facto-Standard für die Dokumentation in Kotlin-Projekten.

So sieht ein einfaches Beispiel aus:

/**\n * Berechnet den Rabatt für einen Benutzer basierend auf seinem Status.\n *\n * @param price Ursprünglicher Preis des Artikels.\n * @param userLevel Benutzerstufe (BRONZE, SILVER, GOLD).\n * @return Endpreis mit Rabatt.\n * @throws IllegalArgumentException Wenn price negativ ist.\n */\nfun calculateDiscount(price: Double, userLevel: UserLevel): Double {\n    // Logik\n}

Beachten Sie: KDoc verwendet die Tags @param, @return, @throws. Aber im Gegensatz zu JavaDoc können Sie Markdown direkt innerhalb des Kommentars schreiben. Das ist praktisch für Listen, Links und Formatierungen.

Beste Praktiken für KDoc

\n
• Schreiben Sie für Menschen, nicht für Maschinen. Wiederholen Sie nicht, was aus dem Code offensichtlich ist. Schreiben Sie statt // setzt den Wert lieber // Setzt den Wert, der für die Steuerberechnung verwendet wird.
\n
• Dokumentieren Sie die öffentliche API. Interne Funktionen (private oder internal) können Sie kurz dokumentieren oder ganz weglassen.
\n
• Verwenden Sie @see und @sample. Verweisen Sie auf verwandte Funktionen oder Anwendungsbeispiele.
\n
• Vergessen Sie nicht @receiver für Erweiterungsfunktionen.
\n

Dokka: Kommentare in schöne Dokumentation verwandeln

Dokka ist ein Dokumentationsgenerator für Kotlin. Er kann HTML, Markdown, JavaDoc und sogar Dokumentation für plattformübergreifende Projekte erstellen. Wenn Sie eine Bibliothek schreiben oder im Team arbeiten, ist Dokka Ihr bester Freund.

Die Installation ist einfach. Fügen Sie in build.gradle.kts das Plugin hinzu:

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}

Führen Sie dann den Befehl aus:

./gradlew dokkaHtml

Dokka generiert einen Ordner build/dokka/html mit einer schönen Dokumentation, die alle Ihre KDoc-Kommentare, die Klassenhierarchie und sogar Links zu den Quellen enthält.

Tipps für Dokka

\n
• Konfigurieren Sie Logo und Projektbeschreibung in dokkaConfiguration;
\n
• Verwenden Sie @suppress, um Unerwünschtes auszublenden