Verbessern Sie Ihre Dokumentation und Ihren Codetest in einem einfachen Schritt mit Beispielfunktionen.
Die zentralen Thesen
- Beispielfunktionen in Go sind testbare Codeschnipsel, die als Dokumentation dienen und zur Überprüfung der Korrektheit verwendet werden können.
- Beispielfunktionen folgen einer Namenskonvention und können für Pakete, Funktionen, Typen und Methoden definiert werden.
- Beispielfunktionen sind ausführbare Tests und können verwendet werden, um zuverlässigen Code sicherzustellen und die Dokumentation auf dem neuesten Stand zu halten.
Eine der Stärken von Go ist die Fülle an integrierten Test- und Dokumentationsfunktionen. Dazu gehört ein äußerst nützliches Tool namens „Beispielfunktionen“, mit dem Sie Ihren Code überprüfen und anderen erklären können.
Als Go-Entwickler sollten Sie genau verstehen, was Beispielfunktionen sind und wie Sie sie zum Erstellen wartbarer Software verwenden können.
Was sind Beispielfunktionen?
Beispielfunktionen (oder Beispiele) in Golang sind testbare Codeausschnitte, die Sie als Dokumentation zu einem Paket hinzufügen und auf Richtigkeit überprüfen können. Beispielfunktionen akzeptieren keine Parameter und geben auch kein Ergebnis zurück.
Stellen Sie sich vor, Sie haben Folgendes Multiplizieren Funktion in Ihrem Projekt:
funcMultiply(a, b int)int {
return a * b
}
Eine Beispielfunktion für Multiplizieren wird so aussehen:
funcExampleMultiply() {
fmt.Println(Multiply(4, 5))
// Output: 2
}
Beispielfunktionen verwenden eine ähnliche Namenskonvention wie Testfunktionen. Definieren Sie ein Funktionsbeispiel, indem Sie den Namen der Funktion als Suffix zu „Example“ hinzufügen, wie es bei „Beispiel“ der Fall ist BeispielMultiplizieren Hier.
Beispielfunktionen genauer betrachten
Der Code im vorherigen Abschnitt zeigt die Grundstruktur einer Beispielfunktion. Ein Beispiel besteht aus dem Namen, dem Funktionskörper und einem optionalen Ausgabekommentar am Ende der Funktion.
Wenn Sie den Ausgabekommentar hinzufügen, kompiliert Go das Beispiel und führt es aus, um seine Richtigkeit zu überprüfen. Ohne den Kommentar kompiliert Go jedoch nur die Beispielfunktion und führt sie nicht aus.
Sie können ein Beispiel für ein Paket, eine Funktion, einen Typ und eine Methode für einen Typ definieren.
Das Definieren von Beispielen für verschiedene Entitäten erfordert unterschiedliche Ansätze.
- Um ein Beispiel für ein Paket zu definieren, rufen Sie einfach Ihre Funktion auf Beispiel(), ohne Suffix. Hier ist zum Beispiel ein Beispiel auf Paketebene:
funcExample() {
fmt.Println("Hello, world!")
// Output:
// Hello, world!
} - Um ein Beispiel für eine Funktion zu definieren, fügen Sie einfach den Funktionsnamen als Suffix hinzu, wie Sie zuvor gelernt haben.
funcExampleMultiply() {
fmt.Println(Multiply(4,5))
// Output: 2
} - Um ein Beispiel für einen Typ zu definieren, fügen Sie den Namen als Suffix hinzu Beispiel. Hier ist ein Beispiel:
type MyStruct struct {
// ...
}funcExampleMyStruct() {
// ...
} - Und schließlich fügen Sie für eine Methode für einen bestimmten Typ den Typnamen, einen Unterstrich und dann den Methodennamen hinzu. Hier ist eine Demonstration:
func(m *MyStruct)MyMethod() {
// ...
}funcExampleMyStruct_MyMethod() {
// ...
}
Sie können mehrere Beispiele für eine Entität definieren, indem Sie einen zusätzlichen Unterstrich und ein Suffix hinzufügen, das mit einem Kleinbuchstaben beginnt. Zum Beispiel, BeispielMultiply_second, BeispielMyStruct_MyMethod_second.
Sie können auch ein größeres Beispiel verwenden, um komplexe Logik zu erklären, indem Sie a verwenden Beispiel für eine ganze Datei.
Ein Beispiel für eine ganze Datei ist eine Datei mit der Endung _test.go und enthält genau eine Beispielfunktion, keine Test- oder Benchmark-Funktionen und mindestens eine weitere Deklaration auf Paketebene. Bei der Anzeige solcher Beispiele zeigt Godoc die gesamte Datei an. - Der Go-Entwickler-Blog
Die Go-Engine erkennt und verarbeitet Ihre Beispielfunktionen entsprechend Ihrer Definition.
Du kannst den... benutzen Ungeordnete Ausgabe Alternative für Ausgabekommentare. Dies ist besonders nützlich in Szenarien, in denen Ihre Funktion eine Liste zurückgibt, die in einer bestimmten Reihenfolge nicht erwartet wird.
Dokumentieren Sie Ihren Code mit Beispielfunktionen
Beispielfunktionen sind sowohl für Dokumentations- als auch für Testzwecke nützlich. Eine Beispielfunktion erklärt das Verhalten normalerweise besser als Kommentare.
So wie Javas Javadoc, Geht Integriertes Dokumentationstool, godoc, hilft bei der einfachen Dokumentation von Code. Sie möchten jedoch einige Bibliotheken und Funktionen gemeinsam dokumentieren, um ein umfassenderes Verständnis ihrer Funktionsweise zu vermitteln. Beispiele beseitigen diesen Nachteil, da sie die Interaktionen zwischen verschiedenen Einheiten eines Pakets veranschaulichen können.
Der godoc Das Tool ordnet Beispiele abhängig von Ihren Spezifikationen automatisch den Funktionen, Typen und Paketen zu, zu denen sie gehören. Es geht noch einen Schritt weiter und ermöglicht das Experimentieren innerhalb der Dokumentations-Weboberfläche.
Sie können ein Paket oder eine Methode direkt in der Dokumentation ausprobieren, bevor Sie sie überhaupt in Ihrem Code verwenden.
Dieses Bild zeigt ein Beispiel dafür json. Gültig Funktion unter Kodierung/json:
Verwenden von Beispielfunktionen zum Unit-Test
Go-Beispielfunktionen sind ebenfalls ausführbare Tests. Wenn Sie das ausführen geh testen Mit dem Befehl führt die Engine jede Beispielfunktion mit einem abschließenden Ausgabekommentar aus und stellt sicher, dass ihre Ausgabe mit dem Inhalt des Kommentars übereinstimmt.
Diese Funktion ist in vielerlei Hinsicht nützlich. Es kann als zusätzliche Schicht dienen Tests, um zuverlässigen Code sicherzustellenAußerdem hilft es Ihnen, den Überblick über Ihre Dokumentation zu behalten, wenn sich Ihr Code ändert.
Wenn Sie beispielsweise eine Änderung vornehmen, die sich darauf auswirkt, wie eine bestimmte Funktion ausgeführt wird und welches Ergebnis sie zurückgibt. Wenn Sie den Ausgabekommentar im Beispiel nicht aktualisieren, um die neuen Änderungen zu berücksichtigen, schlagen die Tests für dieses Beispiel fehl.
Dies trägt wesentlich dazu bei, veraltete Dokumentation zu verhindern, da Ihre Dokumentation immer auf dem neuesten Stand des Codes ist.
Beispielfunktionen erzeugen zuverlässigen Code und Dokumentation
Dokumentation ist ein wesentlicher Bestandteil der Softwareentwicklung, aber nur wenige Sprachen bieten Ihnen eine so leistungsstarke Plattform zum Dokumentieren und Testen Ihres Codes.
Go enthält alles, was Sie zum Erstellen hochwertiger Dokumentation für Ihre Software benötigen, und Beispielfunktionen sind ein wesentlicher Bestandteil davon. Verwenden Sie Beispiele, um Benutzern und Mitarbeitern zu helfen, Ihren Code schneller zu übernehmen und zu verstehen.