Wenn Sie an das Programmieren denken, konzentrieren Sie sich natürlich auf Themen wie Sprachen, Algorithmen und Debugging. Aber die technische Dokumentation kann genauso wichtig sein, um sie richtig zu machen.

Ohne gute Dokumentation kann die Wiederverwendbarkeit von Code leiden. Benutzer, die neu in einer Codebasis sind, können leicht verloren gehen oder frustriert sein, wenn die Dokumentation nicht auf dem neuesten Stand ist. Es ist nicht nur wichtig zu verstehen, was ein Programm tut, sondern auch wie – oder sogar warum – es es tut.

Pakete wie Pydoc für Python und Javadoc für Java helfen, indem sie einen Teil des Prozesses automatisieren. Das Godoc-Tool macht genau das gleiche für Go.

Was ist Godoc?

Godoc ist ein Go-Paket, mit dem Sie Go-Dokumentation auf „die Go-Weise“ erstellen, verwalten und verwenden können. Der Go-Weg ist eine Reihe von Prinzipien, die Sie als Go-Programmierer befolgen sollten, um die Codequalität zu verbessern.

Mit Godoc können Sie ganz einfach die Dokumentation und den Code anderer Entwickler lesen. Sie können auch die Erstellung Ihrer eigenen Dokumentation automatisieren und diese mit Godoc veröffentlichen.

instagram viewer

Godoc ist ähnlich wie Javadoc, der Codedokumentierer für Java. Beide verwenden Kommentare und Code in Modulen, um Dokumentation zu generieren. Und beide Tools strukturieren diese Dokumentation in HTML, sodass Sie sie in einem Browser anzeigen können.

Erste Schritte mit Godoc

Die Verwendung von Godoc ist einfach. Installieren Sie zunächst das Godoc-Paket von der Golang-Website mit diesem Befehl:

gehen Holen Sie sich golang.org/x/tools/cmd/godoc

Wenn Sie diesen Befehl ausführen, wird Godoc in Ihrem angegebenen Arbeitsbereich installiert. Sobald es abgeschlossen ist, sollten Sie in der Lage sein, die auszuführen godoc Befehl in einem Terminal. Wenn bei Ihrer Installation Fehler auftreten, versuchen Sie, Go auf eine neuere Version zu aktualisieren.

Godoc sucht nach ein- und mehrzeiligen Kommentaren, um sie in die von ihm generierte Dokumentation aufzunehmen.

Stellen Sie sicher, dass Sie den Code wie in beschrieben formatieren die Effective Go-Publikation vom Go-Team für die besten Ergebnisse.

Hier ist ein Beispiel mit einzeiligen Kommentaren im C++-Stil:

// Benutzer ist ein Strukturmodell, das enthält
Typ Benutzer Struktur {
}

Sie können auch Blockkommentare im C-Stil verwenden:

/* 
Benutzer ist eine benutzerdefinierte Datenstruktur
Sie können hier beliebigen Text einfügen und der Godoc-Server formatiert ihn, wenn Sie ihn ausführen.
*/
Typ Benutzer Struktur {
}

In den obigen Kommentaren beginnt „Benutzer“ die Sätze, da der Kommentar beschreibt, was die Benutzerstruktur tut. Dies ist eines der vielen Themen, die der Go Way behandelt. Es ist wichtig, Dokumentationssätze mit einem sinnvollen Namen zu beginnen, da der erste Satz in der Paketliste erscheint.

Betreiben eines Godoc-Servers

Sobald Sie Ihren Code kommentiert haben, können Sie die ausführen godoc Befehl in Ihrem Terminal aus dem Codeverzeichnis Ihres Projekts.

Herkömmlicherweise verwenden Go-Entwickler port 6060 Dokumentation zu hosten. Dies ist der Befehl zum Ausführen eines Godoc-Servers auf diesem Port:

godoc -http=:6060

Der obige Befehl hostet Ihre Codedokumentation localhost oder 127.0.0.1. Der Port muss nicht 6060 sein; godoc läuft auf jedem freien Port. Es ist jedoch immer am besten, die Go-Dokumentationskonventionen zu befolgen.

Nachdem Sie den Befehl ausgeführt haben, können Sie Ihre Dokumentation in einem Browser anzeigen, indem Sie besuchen lokaler Host: 6060. Die Zeit, die Godoc benötigt, um Ihre Dokumentation zu erstellen, hängt von ihrer Größe und Komplexität ab.

Der folgende Code folgt dem Go-Weg, in diesem Fall mit einzeiligen Kommentaren.

// Name des Pakets
Paket Benutzer
// fmt ist für die Formatierung zuständig
importieren (
 "fmt"
)


// User ist eine Struktur menschlicher Daten
Typ Benutzer Struktur {
 Das Alter int
 Name Schnur
}


Funkhauptsächlich() {
// human ist eine Initialisierung der User-Struktur
 Mensch := Benutzer {
 Das Alter: 0,
 Name: "Person",
 }


fmt. Println (Mensch. Sich unterhalten())
}
// Talk ist eine Methode der User-Struktur
Funk(Empfänger Benutzer)Sich unterhalten()Schnur {
Rückkehr "Jeder Benutzer darf etwas sagen!"
}

Wenn Sie Godoc auf dem obigen Codemodul ausführen, sollten Sie eine Ausgabe sehen, die in etwa so aussieht:

Beachten Sie, dass es sich um ein vertrautes Format handelt, ähnlich dem, das Sie auf der offiziellen Dokumentations-Website von Go finden.

Godoc verwendet den Kommentar vor der Paketdeklaration als Überblick. Stellen Sie sicher, dass dieser Kommentar beschreibt, was Ihr Programm tut.

Das Index enthält Links zu den Typdeklarationen und Methoden, damit Sie schnell dorthin navigieren können.

Godoc bietet auch Funktionen zum Anzeigen des Quellcodes, aus dem das Paket in der Paketdateien Sektion.

Verbessern Sie Ihre Dokumentation mit Godoc

Sie können mehr als nur einfachen Text in Ihre Godoc-Dokumentation aufnehmen. Sie können URLs hinzufügen, für die Godoc Links generiert, und Ihre Kommentare in Absätze strukturieren.

Wenn Sie auf eine Ressource verlinken möchten, schreiben Sie die URL in Ihren Kommentar, und Godoc erkennt sie und fügt einen Link hinzu. Lassen Sie für Absätze eine leere Kommentarzeile.

// Paket main
Paket hauptsächlich
// Dokument repräsentiert ein normales Dokument.
//
// Link zu https://google.com
Typ Dokumentieren Struktur {
 Seiten int
 Verweise Schnur
 unterzeichnet bool
}


// Write schreibt ein neues Dokument in den Speicher
//
// Auf Wikipedia.com können Sie etwas über das Schreiben lernen
FunkSchreiben() {
}

Beachten Sie, dass Godoc verlangt, dass Sie URLs vollständig ausschreiben, damit es sie verlinken kann. In diesem Beispiel enthält die Google-URL die https:// Präfix, also fügt Godoc einen Link hinzu. Da die Wikipedia-Domain selbst keine vollständige URL ist, wird Godoc sie in Ruhe lassen.

Hier sind einige der besten Prinzipien, die Sie beim Dokumentieren Ihres Go-Codes anwenden sollten:

  • Halten Sie Ihre Dokumentation einfach und prägnant.
  • Beginnen Sie den Satz von Funktionen, Typen und Variablendeklarationen mit ihren Namen.
  • Beginnen Sie eine Zeile mit einem Einzug, um sie als Code vorzuformatieren.
  • Kommentare, die mit „BUG(name)“ beginnen, wie „BUG(joe): This does not work“, sind etwas Besonderes. Godoc wird sie als Fehler erkennen und sie in einem eigenen Abschnitt der Dokumentation melden.

Godoc kann Ihre Dokumentationsprobleme lindern

Mit Godoc können Sie produktiver sein und sich weniger Gedanken über den Aufwand machen, Ihre Programme von Hand zu dokumentieren.

Sie sollten Ihre Dokumentation präzise, ​​detailliert und auf den Punkt bringen, damit sie für Ihre Zielgruppe leichter lesbar und verständlich ist. Es ist auch wichtig, dass Sie Codekommentare auf dem neuesten Stand halten, wenn Sie Ihr Programm ändern.

Sehen Sie sich die Godoc-Paketdokumentation an, um mehr über die Verwendung von Godoc zu erfahren.