Als je aan programmeren denkt, is het normaal om je te concentreren op onderwerpen als talen, algoritmen en foutopsporing. Maar technische documentatie kan net zo belangrijk zijn om het goed te doen.

Zonder goede documentatie kan de herbruikbaarheid van code eronder lijden. Gebruikers die nieuw zijn met een codebase kunnen gemakkelijk verdwalen of gefrustreerd raken als de documentatie niet op orde is. Het is niet alleen belangrijk om te begrijpen wat een programma doet, maar ook hoe - of zelfs waarom - het het doet.

Pakketten zoals Pydoc voor Python en Javadoc voor Java helpen door een deel van het proces te automatiseren. De Godoc-tool doet precies hetzelfde voor Go.

Wat is Godoc?

Godoc is een Go-pakket waarmee u Go-documentatie kunt maken, beheren en gebruiken in "the Go-manier". De Go-manier is een reeks principes die u als Go-programmeur moet volgen om de codekwaliteit te verbeteren.

Met Godoc kunt u gemakkelijk de documentatie en code van andere ontwikkelaars lezen. U kunt ook het maken van uw eigen documentatie automatiseren en publiceren met Godoc.

instagram viewer

Godoc lijkt op Javadoc, de codedocumentator voor Java. Ze gebruiken allebei opmerkingen en code in modules om documentatie te genereren. En beide tools structureren die documentatie in HTML, zodat u deze in een browser kunt bekijken.

Aan de slag met Godoc

Het gebruik van Godoc is eenvoudig. Installeer om te beginnen het Godoc-pakket vanaf de golang-website met behulp van deze opdracht:

Gaan krijg golang.org/x/tools/cmd/godoc

Als u deze opdracht uitvoert, wordt Godoc in uw opgegeven werkruimte geïnstalleerd. Zodra het is voltooid, zou u in staat moeten zijn om de godoc commando in een terminal. Als er fouten zijn met uw installatie, probeer dan Go bij te werken naar een recente versie.

Godoc zoekt naar enkele en meerregelige opmerkingen om op te nemen in de documentatie die het genereert.

Zorg ervoor dat u de code op de Go-manier formatteert, zoals uitgelegd in de Effective Go-publicatie door het Go-team voor de beste resultaten.

Hier is een voorbeeld met enkelregelige opmerkingen in C++-stijl:

// Gebruiker is een structmodel met
type Gebruiker structureren {
}

U kunt ook blokopmerkingen in C-stijl gebruiken:

/* 
Gebruiker is een aangepaste gegevensstructuur
U kunt hier elke tekst opnemen en de Godoc-server formatteert deze wanneer u deze uitvoert.
*/
type Gebruiker structureren {
}

In de bovenstaande opmerkingen begint "Gebruiker" de zinnen omdat de opmerking beschrijft wat de gebruikersstruct doet. Dit is een van de vele onderwerpen die de Go-manier bespreekt. Het starten van documentatiezinnen met een bruikbare naam is cruciaal aangezien de eerste zin in de pakketlijst verschijnt.

Een Godoc-server draaien

Nadat u uw code heeft becommentarieerd, kunt u de godoc commando in uw terminal, vanuit de codedirectory van uw project.

Conventioneel gebruiken Go-ontwikkelaars poort 6060 documentatie te hosten. Dit is het commando om een ​​Godoc-server op die poort te draaien:

godoc -http=:6060

De bovenstaande opdracht host uw codedocumentatie op: localhost, of 127.0.0.1. De poort hoeft niet 6060 te zijn; godoc zal draaien op elke onbezette poort. Het is echter altijd het beste om de Go-documentatieconventies te volgen.

Nadat u de opdracht hebt uitgevoerd, kunt u uw documentatie in een browser bekijken door naar localhost: 6060. De tijd die Godoc nodig heeft om uw documentatie te genereren, hangt af van de grootte en complexiteit ervan.

De onderstaande code houdt zich aan de Go-manier, in dit geval met opmerkingen van één regel.

// naam van het pakket
pakket gebruiker
// fmt is verantwoordelijk voor de opmaak
importeren (
 "fmt"
)


// Gebruiker is een structuur van menselijke gegevens
type Gebruiker structureren {
 Leeftijd int
 Naam snaar
}


funchoofd() {
// mens is een initialisatie van de gebruikersstructuur
 mens := Gebruiker {
 Leeftijd: 0,
 Naam: "persoon",
 }


fmt. Println (mens. Praten())
}
// Talk is een methode van de User struct
func(ontvanger gebruiker)Praten()snaar {
opbrengst "Elke gebruiker mag iets zeggen!"
}

Als u Godoc uitvoert op de bovenstaande codemodule, zou u de uitvoer er ongeveer als volgt uit moeten zien:

Merk op dat het in een bekend formaat is, vergelijkbaar met wat je op de officiële Go-documentatiewebsite vindt.

Godoc gebruikt de opmerking voorafgaand aan de pakketdeclaratie als de Overzicht. Zorg ervoor dat deze opmerking beschrijft wat uw programma doet.

De Inhoudsopgave bevat koppelingen naar de typedeclaraties en methoden, zodat u er snel naartoe kunt navigeren.

Godoc biedt ook functionaliteit voor het bekijken van de broncode waaruit het pakket bestaat in de Pakketbestanden sectie.

Uw documentatie verbeteren met Godoc

U kunt meer dan alleen platte tekst opnemen in uw Godoc-documentatie. U kunt URL's toevoegen waarvoor Godoc links genereert en uw opmerkingen in paragrafen structureren.

Als je naar een bron wilt linken, schrijf dan de URL in je commentaar, en Godoc zal het herkennen en een link toevoegen. Laat voor alinea's een lege commentaarregel achter.

// Pakket hoofd
pakket hoofd
// Document vertegenwoordigt een regulier document.
//
// Link naar https://google.com
type Document structureren {
 Pagina's int
 referenties snaar
 ondertekend bool
}


// Schrijven schrijft een nieuw document naar de opslag
//
// Je kunt leren over schrijven op Wikipedia.com
funcSchrijven() {
}

Merk op dat Godoc vereist dat u URL's volledig uitschrijft om ze te kunnen linken. In dit voorbeeld bevat de Google-URL de https:// prefix, dus Godoc voegt er een link aan toe. Aangezien het Wikipedia-domein op zichzelf geen volledige URL is, laat Godoc het met rust.

Hier zijn enkele beste principes die u kunt toepassen bij het documenteren van uw Go-code:

  • Houd uw documentatie eenvoudig en beknopt.
  • Begin de zin van functies, typen en variabele declaraties met hun naam.
  • Begin een regel met een inspringing om deze vooraf als code op te maken.
  • Opmerkingen die beginnen met "BUG(naam)" zoals "BUG(joe): Dit werkt niet" zijn speciaal. Godoc zal ze herkennen als bugs en ze rapporteren in hun eigen sectie van de documentatie.

Godoc kan uw documentatieproblemen verlichten

Met Godoc kunt u productiever zijn en hoeft u zich minder zorgen te maken over het handmatig documenteren van uw programma's.

U moet uw documentatie nauwkeurig, gedetailleerd en to the point houden om het voor uw doelgroep gemakkelijker te maken om te lezen en te begrijpen. Het is ook van vitaal belang dat u code-opmerkingen up-to-date houdt terwijl u uw programma wijzigt.

Bekijk de documentatie van het Godoc-pakket voor meer informatie over het gebruik van Godoc.