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

Warum Dokumentation in Go eine Superkraft ist und keine langweilige Pflicht

Stellen Sie sich vor: Sie öffnen ein fremdes Go-Projekt und dort – kein einziger Kommentar. Funktionen heißen f1, f2 und Strukturen Data und MoreData. Kommt Ihnen das bekannt vor? Wenn ja, dann wissen Sie, wie schnell Begeisterung dem Wunsch weicht, das Repository zu schließen.

Go ist eine Sprache, die Einfachheit und Klarheit liebt. Aber selbst der sauberste Code spricht nicht immer für sich. Gute Dokumentation in Go ist nicht nur eine "nette Geste" gegenüber Kollegen. Sie ist ein professionelles Werkzeug, das:

\n
• Das Onboarding neuer Entwickler beschleunigt;
\n
• Hilft, Fehler zu vermeiden (erinnern Sie sich, dass Kommentare vor einer falschen API-Nutzung schützen können?);
\n
• Automatisch schöne Seiten auf pkg.go.dev generiert;
\n
• Die Codequalität verbessert (versuchen Sie, einen Kommentar zu einer schlechten Funktion zu schreiben – Sie werden sie selbst umschreiben wollen).
\n

In diesem Artikel behandeln wir die Best Practices für die Dokumentation von Go-Projekten. Von den grundlegenden Regeln von godoc bis hin zu realen Beispielen, die Sie noch heute anwenden können. Los geht's!

Die Philosophie der Dokumentation in Go: Weniger Worte – mehr Bedeutung

Go ist nicht Java oder Python. Niemand schreibt hier mehrseitige Javadoc oder 20-zeilige Docstrings. Die Philosophie von Go ist einfach: Dokumentieren Sie das Verhalten, nicht die Implementierung.

Im offiziellen Leitfaden Effective Go wird klar gesagt: Kommentare sollten beschreiben, was der Code tut, nicht wie. Wenn Ihr Code so komplex ist, dass eine Erklärung des Algorithmus unerlässlich ist – dann sollte er vielleicht vereinfacht werden.

Die grundlegenden Prinzipien:

\n
• Ein Kommentar ist ein Satz. Beginnen Sie mit dem Namen der Funktion oder des Typs. // Calculate returns the result of the calculation. – hervorragend. // This function calculates... – verliert den Fokus.
\n
• Schreiben Sie auf Englisch. Go ist eine internationale Sprache, und Dokumentation auf Englisch ist der De-facto-Standard. Aber wenn Ihr Projekt streng für ein russischsprachiges Team ist, können Sie auch Russisch verwenden. Hauptsache, es ist einheitlich.
\n
• Erklären Sie nicht das Offensichtliche. // SetName sets the name – nutzlos. Besser: // SetName updates the user's display name. Must be called before Save.
\n

Godoc: Ihr bester Freund und automatischer Dokumentator

Go wird mit dem integrierten Tool godoc ausgeliefert. Es parst Kommentare direkt aus dem Code und erstellt HTML-Dokumentation. Das bedeutet, dass Ihre Dokumentation neben dem Code lebt – und gleichzeitig aktualisiert wird.

Wie funktioniert das? Ganz einfach. Schreiben Sie einen Kommentar direkt vor die exportierte Entität (Funktion, Typ, Struktur, Konstante) – und godoc übernimmt ihn.

Beispiel für ein einfaches Paket:

// Package calculator provides basic arithmetic operations.\npackage calculator\n\n// Add returns the sum of two integers.\nfunc Add(a, b int) int {\n    return a + b\n}\n\n// Subtract returns the difference of two integers.\nfunc Subtract(a, b int) int {\n    return a - b\n}

Starten Sie nun godoc -http :8080 und öffnen Sie den Browser. Sie sehen eine schöne Seite mit der Beschreibung des Pakets und jeder Funktion. Magie!

Regeln der guten Etikette für godoc

\n
• Kommentieren Sie immer das Paket. Der Paketkommentar ist das Erste, was der Benutzer sieht. Er sollte den Zweck des Pakets beschreiben und idealerweise ein Anwendungsbeispiel enthalten.
\n
• Vergessen Sie nicht Typen und Strukturen. Wenn eine Struktur Felder hat, die nicht offensichtlich sind, dokumentieren Sie auch diese.
\n
• Verwenden Sie eine Leerzeile. godoc interpretiert den ersten Absatz als Kurzbeschreibung und den Rest als Details. Trennen Sie sie durch eine Leerzeile.
\n

// User repre