Når du tænker på programmering, er det naturligt at fokusere på emner som sprog, algoritmer og fejlretning. Men teknisk dokumentation kan være lige så vigtig at få rigtigt.

Uden god dokumentation kan kodegenanvendelighed lide. Brugere, der er nye til en kodebase, kan nemt gå tabt eller frustrerede, hvis dokumentationen ikke er op til bunden. Det er ikke kun vigtigt at forstå, hvad et program gør, men hvordan – eller endda hvorfor – det gør det.

Pakker som Pydoc til Python og Javadoc til Java hjælper ved at automatisere en del af processen. Godoc-værktøjet gør præcis det samme for Go.

Hvad er Godoc?

Godoc er en Go-pakke, der lader dig oprette, administrere og bruge Go-dokumentation på "the Go-vejen". Go-vejen er et sæt principper, som du som Go-programmør bør følge for at forbedre kodekvaliteten.

Ved at bruge Godoc kan du nemt læse andre udvikleres dokumentation og kode. Du kan også automatisere oprettelsen af ​​din egen dokumentation og udgive den ved hjælp af Godoc.

Godoc ligner Javadoc, kodedokumentatoren til Java

instagram viewer
. De bruger begge kommentarer og kode i moduler til at generere dokumentation. Og begge værktøjer strukturerer den dokumentation i HTML, så du kan se den i en browser.

Kom godt i gang med Godoc

Det er nemt at bruge Godoc. For at begynde skal du installere Godoc-pakken fra golang-webstedet ved hjælp af denne kommando:

gå få golang.org/x/tools/cmd/godoc

Hvis du kører denne kommando, installeres Godoc i dit angivne arbejdsområde. Når den er færdig, bør du være i stand til at køre godoc kommando i en terminal. Hvis der er nogen fejl med din installation, så prøv at opdatere Go til en nyere version.

Godoc leder efter kommentarer på én eller flere linjer, der skal inkluderes i den dokumentation, den genererer.

Sørg for at formatere kode på Go-vejen, som forklaret i Effective Go-publikationen af Go-teamet for de bedste resultater.

Her er et eksempel, hvor du bruger C++-lignende kommentarer:

// Bruger er en strukturmodel, der indeholder
type Bruger struktur {
}

Du kan også bruge C-stil blokkommentarer:

/* 
Bruger er en tilpasset datastruktur
Du kan inkludere enhver tekst her, og Godoc-serveren vil formatere den, når du kører den.
*/
type Bruger struktur {
}

I kommentarerne ovenfor begynder "Bruger" sætningerne, fordi kommentaren beskriver, hvad brugerstrukturen gør. Dette er et af de mange emner, som Go-vejen diskuterer. At starte dokumentationssætninger med et brugbart navn er afgørende, da den første sætning vises i pakkelisten.

Kører en Godoc-server

Når du har kommenteret din kode, kan du køre godoc kommando i din terminal fra dit projekts kodemappe.

Konventionelt bruger Go-udviklere port 6060 at være vært for dokumentation. Dette er kommandoen til at køre en Godoc-server på den port:

godoc -http=:6060

Kommandoen ovenfor hoster din kodedokumentation på localhost eller 127.0.0.1. Porten behøver ikke 6060; godoc vil køre på enhver ledig havn. Det er dog altid bedst at følge Go-dokumentationskonventionerne.

Når du har kørt kommandoen, kan du se din dokumentation i en browser ved at besøge lokal vært: 6060. Den tid, det tager Godoc at generere din dokumentation, afhænger af dens størrelse og kompleksitet.

Koden nedenfor overholder Go-måden, i dette tilfælde ved hjælp af enkeltlinjekommentarer.

// pakkens navn
pakke bruger
// fmt er ansvarlig for formatering
importere (
 "fmt"
)


// Bruger er en struktur af menneskelige data
type Bruger struktur {
 Alder int
 Navn snor
}


funcvigtigste() {
// human er en initialisering af brugerstrukturen
 menneske := Bruger {
 Alder: 0,
 Navn: "person",
 }


fmt. Println (menneske. Tale())
}
// Talk er en metode til brugerstrukturen
func(modtagerbruger)Tale()snor {
Vend tilbage "Enhver bruger får at sige noget!"
}

Hvis du kører Godoc på kodemodulet ovenfor, bør du se output, der ser sådan ud:

Bemærk, at det er i et velkendt format, der ligner det, du finder på Go's officielle dokumentationswebsted.

Godoc bruger kommentaren forud for pakkeerklæringen som Oversigt. Sørg for, at denne kommentar beskriver, hvad dit program gør.

Det Indeks indeholder links til typedeklarationerne og metoderne, så du hurtigt kan navigere til dem.

Godoc giver også funktionalitet til at se kildekoden, der udgør pakken i Pakke filer afsnit.

Forbedring af din dokumentation ved hjælp af Godoc

Du kan inkludere mere end blot almindelig tekst i din Godoc-dokumentation. Du kan tilføje URL'er, som Godoc vil generere links til og strukturere dine kommentarer i afsnit.

Hvis du vil linke til en ressource, skal du skrive URL'en i din kommentar, og Godoc genkender den og tilføjer et link. For afsnit, efterlad en tom kommentarlinje.

// Pakke hoved
pakke vigtigste
// Dokument repræsenterer et almindeligt dokument.
//
// Link til https://google.com
type Dokument struktur {
 sider int
 referencer snor
 underskrevet bool
}


// Write skriver et nyt dokument til lageret
//
// Du kan lære om at skrive fra Wikipedia.com
funcSkrive() {
}

Bemærk, at Godoc kræver, at du skriver alle URL'er ud, for at den kan linke dem. I dette eksempel inkluderer Google URL'en https:// præfiks, så Godoc tilføjer et link til det. Da Wikipedia-domænet ikke er en fuldstændig URL i sig selv, vil Godoc lade det være.

Her er nogle af de bedste principper at anvende, når du dokumenterer din Go-kode:

  • Hold din dokumentation enkel og kortfattet.
  • Start sætningen af ​​funktioner, typer og variabeldeklarationer med deres navne.
  • Start en linje med et indrykning for at forformatere den som kode.
  • Kommentarer, der begynder "BUG(navn)" som "BUG(joe): Dette virker ikke" er specielle. Godoc vil genkende dem som fejl og rapportere dem i deres egen sektion af dokumentationen.

Godoc kan lette dine dokumentationsproblemer

Ved at bruge Godoc kan du være mere produktiv og bekymre dig mindre om indsatsen med at dokumentere dine programmer i hånden.

Du bør holde din dokumentation præcis, detaljeret og præcis for at gøre det nemmere for din målgruppe at læse og forstå. Det er også vigtigt, at du holder kodekommentarer opdaterede, når du ændrer dit program.

Tjek Godoc-pakkens dokumentation for at lære mere om brugen af ​​Godoc.