Ko razmišljate o programiranju, je naravno, da se osredotočite na teme, kot so jeziki, algoritmi in odpravljanje napak. Toda tehnična dokumentacija je lahko prav tako pomembna, da se pravilno pripravi.

Brez dobre dokumentacije lahko trpi ponovna uporaba kode. Uporabniki, ki so novi v kodni zbirki, se lahko zlahka izgubijo ali razočarajo, če dokumentacija ni popolna. Ni pomembno samo razumeti, kaj program počne, temveč tudi, kako – ali celo zakaj – to počne.

Paketi, kot sta Pydoc za Python in Javadoc za Java, pomagajo z avtomatizacijo dela procesa. Orodje Godoc naredi enako za Go.

Kaj je Godoc?

Godoc je paket Go, ki vam omogoča ustvarjanje, upravljanje in uporabo dokumentacije Go na način Go. Go way je niz načel, ki jih morate kot programer Go upoštevati, da izboljšate kakovost kode.

Z uporabo Godoca lahko preprosto preberete dokumentacijo in kodo drugih razvijalcev. Prav tako lahko avtomatizirate ustvarjanje lastne dokumentacije in jo objavite z uporabo Godoca.

Godoc je podoben Javadoc, dokumentator kode za Javo

instagram viewer
. Oba uporabljata komentarje in kodo v modulih za ustvarjanje dokumentacije. Obe orodji strukturirata to dokumentacijo v HTML, tako da si jo lahko ogledate v brskalniku.

Kako začeti z Godocom

Uporaba Godoca je enostavna. Za začetek namestite paket Godoc s spletnega mesta golang s tem ukazom:

pojdi pridobite golang.org/x/tools/cmd/godoc

Zagon tega ukaza bo namestil Godoc v vaš določen delovni prostor. Ko se konča, bi morali biti sposobni zagnati godoc ukaz v terminalu. Če so pri namestitvi kakršne koli napake, poskusite posodobiti Go na najnovejšo različico.

Godoc išče eno- in večvrstične komentarje, ki jih vključi v dokumentacijo, ki jo ustvari.

Prepričajte se, da ste formatirali kodo Go way, kot je razloženo v publikacijo Effective Go s strani ekipe Go za najboljše rezultate.

Tukaj je primer uporabe enovrstičnih komentarjev v slogu C++:

// Uporabnik je model strukture, ki vsebuje
tip Uporabnik struct {
}

Uporabite lahko tudi blok komentarje v slogu C:

/* 
Uporabnik je struktura podatkov po meri
Tukaj lahko vključite poljubno besedilo in strežnik Godoc ga bo formatiral, ko ga zaženete.
*/
tip Uporabnik struct {
}

V zgornjih komentarjih »Uporabnik« začne stavke, ker komentar opisuje, kaj počne struktura User. To je ena od mnogih tem, o katerih razpravlja Go way. Začetek dokumentacijskih stavkov z uporabnim imenom je ključnega pomena, saj se prvi stavek pojavi na seznamu paketov.

Zagon strežnika Godoc

Ko komentirate svojo kodo, lahko zaženete godoc ukaz v vašem terminalu iz imenika kode vašega projekta.

Običajno razvijalci Go uporabljajo vrata 6060 gostiti dokumentacijo. To je ukaz za zagon strežnika Godoc na teh vratih:

godoc -http=:6060

Zgornji ukaz gosti dokumentacijo vaše kode localhost ali 127.0.0.1. Pristanišče ne potrebuje 6060; godoc bo deloval na vseh nezasedenih pristaniščih. Vendar pa je vedno najbolje slediti konvencijam o dokumentaciji Go.

Ko zaženete ukaz, si lahko dokumentacijo ogledate v brskalniku tako, da obiščete lokalni gostitelj: 6060. Čas, ki ga Godoc porabi za izdelavo vaše dokumentacije, je odvisen od njene velikosti in zapletenosti.

Spodnja koda se drži poti Go, v tem primeru uporablja enovrstične komentarje.

// ime paketa
paket uporabnik
// fmt je odgovoren za oblikovanje
uvoz (
 "fmt"
)


// Uporabnik je struktura človeških podatkov
tip Uporabnik struct {
 starost int
 ime vrvica
}


funcglavni() {
// človek je inicializacija strukture uporabnika
 človek := uporabnik {
 starost: 0,
 Ime: "oseba",
 }


fmt. Println (človeški. Govori ())
}
// Talk je metoda strukture uporabnika
func(uporabnik sprejemnika)Govori()vrvica {
vrnitev "Vsak uporabnik lahko nekaj pove!"
}

Če zaženete Godoc v zgornjem kodnem modulu, bi morali videti izhod, ki izgleda nekako takole:

Upoštevajte, da je v znani obliki, podobno tisti, ki jo najdete na uradni spletni strani dokumentacije Go.

Godoc uporablja komentar pred izjavo paketa kot Pregled. Prepričajte se, da ta komentar opisuje, kaj počne vaš program.

The Indeks vsebuje povezave do deklaracij tipov in metod, tako da se lahko hitro pomaknete do njih.

Godoc ponuja tudi funkcionalnost za ogled izvorne kode, ki sestavlja paket v Paketne datoteke oddelek.

Izboljšanje vaše dokumentacije z uporabo Godoca

V svojo dokumentacijo Godoc lahko vključite več kot samo golo besedilo. Dodate lahko URL-je, za katere bo Godoc ustvaril povezave, in strukturirajte vaše komentarje v odstavke.

Če želite vzpostaviti povezavo do vira, vpišite URL v svoj komentar in Godoc ga bo prepoznal in dodal povezavo. Za odstavke pustite prazno vrstico za komentarje.

// Glavni paket
paket glavni
// Dokument predstavlja navaden dokument.
//
// Povezava do https://google.com
tip dokument struct {
 strani int
 reference vrvica
 podpisana bool
}


// Write zapiše nov dokument v pomnilnik
//
// O pisanju se lahko naučite na Wikipedia.com
funcpiši() {
}

Upoštevajte, da Godoc zahteva, da zapišete URL-je v celoti, da jih poveže. V tem primeru Googlov URL vključuje https:// predpono, zato Godoc ji doda povezavo. Ker domena Wikipedije sama po sebi ni polni URL, jo bo Godoc pustil pri miru.

Tukaj je nekaj najboljših načel, ki jih morate uporabiti pri dokumentiranju kode Go:

  • Naj bo vaša dokumentacija preprosta in jedrnata.
  • Začnite stavek funkcij, vrst in deklaracij spremenljivk z njihovimi imeni.
  • Začnite vrstico z zamikom, da jo vnaprej formatirate kot kodo.
  • Komentarji, ki se začnejo z "BUG(name)", kot je "BUG(joe): To ne deluje", so posebni. Godoc jih bo prepoznal kot hrošče in jih prijavil v svojem delu dokumentacije.

Godoc vam lahko olajša težave z dokumentacijo

Z uporabo Godoca ste lahko bolj produktivni in manj skrbite za ročno dokumentiranje programov.

Dokumentacijo morate hraniti natančno, podrobno in do točke, da bo vaša ciljna publika lažje brala in razumela. Pomembno je tudi, da med spreminjanjem programa posodabljate komentarje kode.

Če želite izvedeti več o uporabi Godoca, si oglejte dokumentacijo paketa Godoc.