Når du tenker på programmering, er det naturlig å fokusere på emner som språk, algoritmer og feilsøking. Men teknisk dokumentasjon kan være like viktig å få riktig.
Uten god dokumentasjon kan gjenbrukbarhet av kode lide. Brukere som er nye i en kodebase, kan lett gå seg vill eller frustrerte hvis dokumentasjonen ikke er på topp. Det er ikke bare viktig å forstå hva et program gjør, men hvordan – eller til og med hvorfor – det gjør det.
Pakker som Pydoc for Python og Javadoc for Java hjelper ved å automatisere deler av prosessen. Godoc-verktøyet gjør akkurat det samme for Go.
Hva er Godoc?
Godoc er en Go-pakke som lar deg lage, administrere og bruke Go-dokumentasjon på «the Go way». Go-veien er et sett med prinsipper som du som Go-programmerer bør følge for å forbedre kodekvaliteten.
Ved å bruke Godoc kan du enkelt lese andre utvikleres dokumentasjon og kode. Du kan også automatisere opprettelsen av din egen dokumentasjon og publisere den ved hjelp av Godoc.
Godoc ligner på Javadoc, kodedokumentatoren for Java
. De bruker begge kommentarer og kode i moduler for å generere dokumentasjon. Og begge verktøyene strukturerer dokumentasjonen i HTML slik at du kan se den i en nettleser.Komme i gang med Godoc
Det er enkelt å bruke Godoc. For å begynne, installer Godoc-pakken fra golang-nettstedet ved å bruke denne kommandoen:
gå skaff deg golang.org/x/tools/cmd/godoc
Å kjøre denne kommandoen vil installere Godoc i det angitte arbeidsområdet. Når den er fullført, bør du kunne kjøre godoc kommando i en terminal. Hvis det er noen feil med installasjonen, prøv å oppdatere Go til en nylig versjon.
Godoc ser etter kommentarer på én og flere linjer som skal inkluderes i dokumentasjonen den genererer.
Sørg for å formatere kode på Go-veien, som forklart i Effektiv Go-publikasjonen av Go-teamet for de beste resultatene.
Her er et eksempel med C++-stil enlinjekommentarer:
// Bruker er en strukturmodell som inneholder
type Bruker struktur {
}
Du kan også bruke blokkkommentarer i C-stil:
/*
Bruker er en tilpasset datastrukturDu kan inkludere hvilken som helst tekst her og Godoc-serveren vil formatere den når du kjører den.
*/
type Bruker struktur {
}
I kommentarene ovenfor begynner "Bruker" setningene fordi kommentaren beskriver hva brukerstrukturen gjør. Dette er et av de mange temaene som Go-veien diskuterer. Å starte dokumentasjonssetninger med et nyttig navn er avgjørende siden den første setningen vises i pakkelisten.
Kjører en Godoc-server
Når du har kommentert koden din, kan du kjøre godoc kommando i terminalen, fra prosjektets kodekatalog.
Konvensjonelt bruker Go-utviklere port 6060 å være vert for dokumentasjon. Dette er kommandoen for å kjøre en Godoc-server på den porten:
godoc -http=:6060
Kommandoen ovenfor er vert for kodedokumentasjonen din localhost, eller 127.0.0.1. Porten trenger ikke 6060; godoc vil kjøre på enhver ledig havn. Det er imidlertid alltid best å følge Go-dokumentasjonskonvensjonene.
Når du har kjørt kommandoen, kan du se dokumentasjonen i en nettleser ved å gå til lokal vert: 6060. Tiden det tar for Godoc å generere dokumentasjonen din, vil avhenge av størrelsen og kompleksiteten.
Koden nedenfor følger Go-veien, i dette tilfellet ved å bruke enlinjekommentarer.
// navnet på pakken
pakke bruker// fmt er ansvarlig for formatering
import (
"fmt"
)// Bruker er en struktur av menneskelige data
type Bruker struktur {
Alder int
Navn streng
}funchoved-() {
// human er en initialisering av brukerstrukturen
menneske := Bruker {
Alder: 0,
Navn: "person",
}fmt. Println (menneske. Snakke())
}
// Talk er en metode for brukerstrukturen
func(mottaker bruker)Snakke()streng {
komme tilbake "Hver bruker får si noe!"
}
Hvis du kjører Godoc på kodemodulen ovenfor, bør du se utdata som ser slik ut:
Legg merke til at den er i et kjent format, lik det du finner på Go offisielle dokumentasjonsnettsted.
Godoc bruker kommentaren foran pakkeerklæringen som Oversikt. Sørg for at denne kommentaren beskriver hva programmet ditt gjør.
De Indeks inneholder lenker til typedeklarasjonene og metodene slik at du raskt kan navigere til dem.
Godoc gir også funksjonalitet for å se kildekoden som utgjør pakken i Pakke filer seksjon.
Forbedre dokumentasjonen din ved å bruke Godoc
Du kan inkludere mer enn bare ren tekst i Godoc-dokumentasjonen. Du kan legge til nettadresser som Godoc vil generere lenker for og strukturere kommentarene dine i avsnitt.
Hvis du vil koble til en ressurs, skriv URL-en i kommentaren din, og Godoc vil gjenkjenne den og legge til en lenke. Legg igjen en tom kommentarlinje for avsnitt.
// Pakke hoved
pakke hoved-// Dokument representerer et vanlig dokument.
//
// Link til https://google.com
type Dokument struktur {
sider int
referanser streng
signert bool
}// Write skriver et nytt dokument til lageret
//
// Du kan lære om skriving fra Wikipedia.com
funcSkrive() {
}
Merk at Godoc krever at du skriver ut URL-er i sin helhet for at den skal koble dem. I dette eksemplet inkluderer Google-URLen https:// prefiks, så Godoc legger til en lenke til den. Siden Wikipedia-domenet ikke er en fullstendig URL i seg selv, vil Godoc la det være.
Her er noen beste prinsipper du kan bruke når du dokumenterer Go-koden din:
- Hold dokumentasjonen enkel og kortfattet.
- Start setningen med funksjoner, typer og variabeldeklarasjoner med navnene deres.
- Start en linje med et innrykk for å forhåndsformatere den som kode.
- Kommentarer som begynner med "BUG(navn)" som "BUG(joe): Dette fungerer ikke" er spesielle. Godoc vil gjenkjenne dem som feil og rapportere dem i sin egen del av dokumentasjonen.
Godoc kan lette dokumentasjonen din
Ved å bruke Godoc kan du være mer produktiv og bekymre deg mindre for arbeidet med å dokumentere programmene dine for hånd.
Du bør holde dokumentasjonen din presis, detaljert og til poenget for å gjøre det lettere for målgruppen å lese og forstå. Det er også viktig at du holder kodekommentarer oppdatert når du endrer programmet.
Sjekk ut Godoc-pakkedokumentasjonen for å lære mer om bruk av Godoc.