Kui mõtlete programmeerimisele, on loomulik keskenduda sellistele teemadele nagu keeled, algoritmid ja silumine. Kuid tehniline dokumentatsioon võib olla õige toimimise jaoks sama oluline.
Ilma korraliku dokumentatsioonita võib koodi korduvkasutatavus kannatada. Uued koodibaasi kasutajad võivad kergesti eksida või pettuda, kui dokumentatsioon ei ole korras. Oluline pole mitte ainult mõista, mida programm teeb, vaid ka seda, kuidas – või isegi miks – see seda teeb.
Sellised paketid nagu Pydoc for Python ja Javadoc for Java aitavad osa protsessist automatiseerida. Godoci tööriist teeb sama ka Go puhul.
Mis on Godoc?
Godoc on Go pakett, mis võimaldab teil luua, hallata ja kasutada Go dokumentatsiooni "Go viisil". Go way on põhimõtete kogum, mida Go programmeerijana peaksite koodi kvaliteedi parandamiseks järgima.
Godoci abil saate hõlpsalt lugeda teiste arendajate dokumentatsiooni ja koodi. Samuti saate automatiseerida oma dokumentatsiooni loomise ja avaldada selle Godoci abil.
Godoc on sarnane
Javadoc, Java koodidokumentaator. Mõlemad kasutavad dokumentatsiooni loomiseks moodulites kommentaare ja koodi. Mõlemad tööriistad struktureerivad selle dokumentatsiooni HTML-i, nii et saate seda brauseris vaadata.Godoci kasutamise alustamine
Godoci kasutamine on lihtne. Alustuseks installige Godoci pakett golangi veebisaidilt, kasutades seda käsku:
mine hankige golang.org/x/tools/cmd/godoc
Selle käsu käivitamine installib Godoci teie määratud tööruumi. Kui see on lõpule jõudnud, peaksite saama käivitada goddoc käsk terminalis. Kui installimisel esineb vigu, proovige värskendada käsku Mine uuemale versioonile.
Godoc otsib ühe- ja mitmerealisi kommentaare, mida ta genereeritavasse dokumentatsiooni lisada.
Vormindage kood kindlasti Go-meetodil, nagu on selgitatud jaotises väljaanne Effective Go Go meeskonna poolt parimate tulemuste saavutamiseks.
Siin on näide C++ stiilis üherealiste kommentaaride kasutamisest:
// Kasutaja on struktuurimudel, mis sisaldab
tüüp Kasutaja struktuur {
}
Võite kasutada ka C-stiilis plokkkommentaare:
/*
Kasutaja on kohandatud andmestruktuurSiia saate lisada mis tahes teksti ja Godoci server vormindab selle käivitamisel.
*/
tüüp Kasutaja struktuur {
}
Ülaltoodud kommentaarides alustab "Kasutaja" lauseid, kuna kommentaar kirjeldab, mida kasutaja struktuur teeb. See on üks paljudest teemadest, mida Go way käsitleb. Dokumentatsioonilausete alustamine kasuliku nimega on ülioluline, kuna esimene lause ilmub paketiloendisse.
Godoci serveri käitamine
Kui olete oma koodi kommenteerinud, saate käivitada goddoc käsk terminalis, teie projekti koodikataloogist.
Tavaliselt kasutavad Go arendajad porti 6060 dokumentatsiooni vastuvõtmiseks. See on käsk Godoci serveri käitamiseks selles pordis:
godoc -http=:6060
Ülaltoodud käsk majutab teie koodi dokumentatsiooni localhost või 127.0.0.1. Port ei pea olema 6060; godoc töötab igas vabas sadamas. Siiski on alati kõige parem järgida Go dokumentatsiooni tavasid.
Kui olete käsu käivitanud, saate oma dokumentatsiooni brauseris vaadata, külastades aadressi kohalik host: 6060. Aeg, mis Godocil teie dokumentatsiooni koostamiseks kulub, sõltub selle suurusest ja keerukusest.
Allolev kood järgib Go-viisi, antud juhul üherealisi kommentaare kasutades.
// paketi nimi
pakett kasutaja// fmt vastutab vormindamise eest
importida (
"fmt"
)// Kasutaja on inimandmete struktuur
tüüp Kasutaja struktuur {
Vanus int
Nimi string
}funcpeamine() {
// inimene on kasutajastruktuuri initsialiseerimine
inimene := Kasutaja {
Vanus: 0,
Nimi: "isik",
}fmt. Println (inimene. Räägi())
}
// Rääkimine on kasutajastruktuuri meetod
func(vastuvõtja kasutaja)Rääkige()string {
tagasi "Iga kasutaja saab midagi öelda!"
}
Kui käivitate Godoci ülaltoodud koodimoodulis, peaksite nägema väljundit umbes selline:
Pange tähele, et see on tuttavas vormingus, mis on sarnane Go ametliku dokumentatsiooni veebisaidiga.
Godoc kasutab pakendi deklaratsioonile eelnevat kommentaari Ülevaade. Veenduge, et see kommentaar kirjeldaks teie programmi tegevust.
The Indeks sisaldab linke tüübideklaratsioonidele ja meetoditele, et saaksite nende juurde kiiresti liikuda.
Godoc pakub ka funktsioone paketi moodustava lähtekoodi vaatamiseks Pakendi failid osa.
Dokumentatsiooni täiustamine Godoci abil
Saate oma Godoci dokumentatsiooni lisada rohkem kui lihtteksti. Saate lisada URL-e, millele Godoc loob lingid, ja struktureerida teie kommentaarid lõikudeks.
Kui soovite linkida mõnele ressursile, kirjutage oma kommentaaridesse URL ja Godoc tunneb selle ära ja lisab lingi. Lõigete jaoks jätke tühi kommentaaririda.
// Paketi põhi
pakett peamine// Dokument tähistab tavalist dokumenti.
//
// Link to https://google.com
tüüp Dokument struktuur {
lehekülgi int
viited string
allkirjastatud bool
}// Write kirjutab salvestusruumi uue dokumendi
//
// Kirjutamise kohta saate teavet saidilt Wikipedia.com
funcKirjutage() {
}
Pange tähele, et Godoc nõuab nende linkimiseks URL-ide täielikku väljakirjutamist. Selles näites sisaldab Google'i URL https:// eesliide, nii et Godoc lisab sellele lingi. Kuna Wikipedia domeen ei ole üksi täielik URL, jätab Godoc selle rahule.
Siin on mõned parimad põhimõtted, mida oma Go-koodi dokumenteerimisel järgida.
- Hoidke oma dokumentatsioon lihtne ja lühike.
- Alustage funktsioonide, tüüpide ja muutujate deklaratsioonide lauset nende nimede järgi.
- Alustage rida taandega, et vormindada see koodina.
- Kommentaarid, mis algavad sõnaga "BUG(nimi)" nagu "BUG(joe): See ei tööta", on erilised. Godoc tuvastab need vigadena ja teatab neist oma dokumentatsiooni jaotises.
Godoc võib teie dokumenteerimisega seotud probleeme leevendada
Godoci abil saate olla produktiivsem ja vähem muretseda programmide käsitsi dokumenteerimise pärast.
Peaksite hoidma oma dokumentatsiooni täpsed, üksikasjalikud ja täpsed, et teie sihtrühmale oleks lihtsam lugeda ja mõista. Samuti on oluline, et hoiaksite programmi muutmisel koodi kommentaarid ajakohasena.
Godoci kasutamise kohta lisateabe saamiseks vaadake Godoci paketi dokumentatsiooni.
