Kada razmišljate o programiranju, prirodno je da se usredotočite na teme kao što su jezici, algoritmi i otklanjanje pogrešaka. Ali tehnička dokumentacija može biti jednako važna za ispravan rad.
Bez dobre dokumentacije, ponovna upotreba koda može patiti. Korisnici koji su novi u bazi kodova mogu se lako izgubiti ili frustrirati ako dokumentacija nije do nule. Nije važno samo razumjeti što program radi, već i kako – ili čak zašto – to čini.
Paketi poput Pydoc za Python i Javadoc za Javu pomažu automatizacijom dijela procesa. Alat Godoc čini isto za Go.
Što je Godoc?
Godoc je Go paket koji vam omogućuje kreiranje, upravljanje i korištenje Go dokumentacije na "The Go way". Go way je skup principa koje biste, kao Go programer, trebali slijediti kako biste poboljšali kvalitetu koda.
Koristeći Godoc, možete jednostavno čitati dokumentaciju i kod drugih programera. Također možete automatizirati izradu vlastite dokumentacije i objaviti je koristeći Godoc.
Godoc je sličan Javadoc, dokumentator koda za Javu
. Obojica koriste komentare i kod u modulima za generiranje dokumentacije. I oba alata strukturiraju tu dokumentaciju u HTML-u tako da je možete vidjeti u pregledniku.Početak rada s Godocom
Korištenje Godoca je jednostavno. Za početak instalirajte paket Godoc s web stranice golang koristeći ovu naredbu:
ići nabavite golang.org/x/tools/cmd/godoc
Izvođenje ove naredbe instalirat će Godoc u navedeni radni prostor. Nakon što završi, trebali biste moći pokrenuti godoc naredba u terminalu. Ako postoje pogreške s vašom instalacijom, pokušajte ažurirati Go na najnoviju verziju.
Godoc traži komentare u jednom i više retka koje će uključiti u dokumentaciju koju generira.
Obavezno formatirajte kod Go way, kao što je objašnjeno u publikacija Effective Go od strane Go tima za najbolje rezultate.
Evo primjera korištenja jednorečnih komentara u stilu C++:
// Korisnik je model strukture koji sadrži
tip Korisnik strukturirati {
}
Također možete koristiti blok komentare u C stilu:
/*
Korisnik je prilagođena struktura podatakaOvdje možete uključiti bilo koji tekst i Godoc poslužitelj će ga formatirati kada ga pokrenete.
*/
tip Korisnik strukturirati {
}
U gornjim komentarima, "Korisnik" počinje rečenice jer komentar opisuje što korisnikova struktura radi. Ovo je jedna od mnogih tema o kojima raspravlja Go way. Započinjanje rečenica dokumentacije s korisnim imenom je ključno jer se prva rečenica pojavljuje na popisu paketa.
Pokretanje Godoc poslužitelja
Nakon što ste komentirali svoj kod, možete pokrenuti godoc naredbu u vašem terminalu, iz direktorija kodova vašeg projekta.
Konvencionalno, Go programeri koriste port 6060 ugostiti dokumentaciju. Ovo je naredba za pokretanje Godoc poslužitelja na tom portu:
godoc -http=:6060
Gornja naredba hostira dokumentaciju vašeg koda localhost, ili 127.0.0.1. Port ne mora 6060; godoc će raditi na bilo kojoj nezauzetoj luci. Međutim, uvijek je najbolje slijediti konvencije Go dokumentacije.
Nakon što pokrenete naredbu, svoju dokumentaciju možete pregledati u pregledniku posjetom lokalni host: 6060. Vrijeme koje je Godocu potrebno za generiranje vaše dokumentacije ovisit će o njezinoj veličini i složenosti.
Kôd u nastavku se pridržava Go way, u ovom slučaju koristeći komentare u jednom retku.
// naziv paketa
paket korisnik// fmt je odgovoran za formatiranje
uvoz (
"fmt"
)// Korisnik je struktura ljudskih podataka
tip Korisnik strukturirati {
Dob int
Ime niz
}funcglavni() {
// human je inicijalizacija strukture User
čovjek := korisnik {
Dob: 0,
Ime: "osoba",
}fmt. Println (ljudski. Razgovor())
}
// Talk je metoda strukture User
func(korisnik primatelja)Razgovor()niz {
povratak "Svaki korisnik može nešto reći!"
}
Ako pokrenete Godoc na kodnom modulu iznad, trebali biste vidjeti izlaz koji izgleda otprilike ovako:
Primijetite da je u poznatom formatu, sličnom onome što ćete pronaći na web-mjestu službene dokumentacije Go.
Godoc koristi komentar koji prethodi deklaraciji paketa kao Pregled. Provjerite opisuje li ovaj komentar što vaš program radi.
The Indeks sadrži veze na deklaracije tipa i metode tako da možete brzo doći do njih.
Godoc također pruža funkcionalnost za pregled izvornog koda koji čini paket u Datoteke paketa odjeljak.
Poboljšanje vaše dokumentacije pomoću Godoca
Možete uključiti više od običnog teksta u svoju Godoc dokumentaciju. Možete dodati URL-ove za koje će Godoc generirati veze i strukturirati vaše komentare u odlomke.
Ako se želite povezati s resursom, upišite URL u svoj komentar i Godoc će ga prepoznati i dodati vezu. Za odlomke ostavite prazan redak komentara.
// Glavni paket
paket glavni// Dokument predstavlja običan dokument.
//
// Poveznica za https://google.com
tip Dokument strukturirati {
stranicama int
reference niz
potpisan bool
}// Write zapisuje novi dokument u pohranu
//
// Možete naučiti o pisanju na Wikipedia.com
funcPisati() {
}
Imajte na umu da Godoc zahtijeva da napišete URL-ove u cijelosti kako bi ih povezao. U ovom primjeru, Google URL uključuje https:// prefiksa, pa Godoc dodaje vezu na njega. Budući da domena Wikipedije nije sama po sebi puni URL, Godoc će je ostaviti na miru.
Evo nekoliko najboljih načela za primjenu kada dokumentirate svoj Go kod:
- Neka vaša dokumentacija bude jednostavna i sažeta.
- Započnite rečenicu funkcija, tipova i deklaracija varijabli njihovim imenima.
- Započnite redak s uvlakom kako biste ga unaprijed formatirali kao kod.
- Komentari koji počinju "BUG(ime)" poput "BUG(joe): Ovo ne radi" posebni su. Godoc će ih prepoznati kao bugove i prijaviti ih u vlastitom dijelu dokumentacije.
Godoc vam može olakšati probleme s dokumentacijom
Koristeći Godoc, možete biti produktivniji i manje se brinuti o naporima da svoje programe dokumentirate ručno.
Svoju dokumentaciju trebate držati preciznom, detaljnom i točnom kako biste je ciljnoj publici lakše čitali i razumjeli. Također je važno da komentare koda održavate ažurnima dok mijenjate svoj program.
Pogledajte dokumentaciju paketa Godoc kako biste saznali više o korištenju Godoc-a.