Keď premýšľate o programovaní, je prirodzené zamerať sa na témy, ako sú jazyky, algoritmy a ladenie. Technická dokumentácia však môže byť rovnako dôležitá pre správne riešenie.

Bez dobrej dokumentácie môže utrpieť opätovná použiteľnosť kódu. Používatelia noví v kódovej základni sa môžu ľahko stratiť alebo frustrovať, ak dokumentácia nie je až do nuly. Nie je dôležité len porozumieť tomu, čo program robí, ale aj ako – alebo dokonca prečo – to robí.

Balíky ako Pydoc pre Python a Javadoc pre Java pomáhajú automatizáciou časti procesu. Nástroj Godoc robí to isté pre Go.

Čo je Godoc?

Godoc je balík Go, ktorý vám umožňuje vytvárať, spravovať a používať dokumentáciu Go spôsobom „Go“. Go way je súbor zásad, ktoré by ste ako programátor Go mali dodržiavať, aby ste zlepšili kvalitu kódu.

Pomocou Godoc môžete ľahko čítať dokumentáciu a kód iných vývojárov. Môžete tiež automatizovať vytváranie vlastnej dokumentácie a publikovať ju pomocou Godoc.

Godoc je podobný Javadoc, dokumentátor kódu pre Java. Obaja používajú komentáre a kód v moduloch na generovanie dokumentácie. A oba nástroje štruktúrujú túto dokumentáciu v HTML, takže si ju môžete prezerať v prehliadači.

instagram viewer

Začíname s Godocom

Používanie Godoc je jednoduché. Ak chcete začať, nainštalujte balík Godoc z webovej stránky golang pomocou tohto príkazu:

ísť získaj golang.org/x/tools/cmd/godoc

Spustenie tohto príkazu nainštaluje Godoc do zadaného pracovného priestoru. Po dokončení by ste mali byť schopní spustiť godoc príkaz v termináli. Ak sa pri inštalácii vyskytnú nejaké chyby, skúste aktualizovať Go na najnovšiu verziu.

Godoc hľadá jednoriadkové a viacriadkové komentáre, ktoré má zahrnúť do dokumentácie, ktorú generuje.

Uistite sa, že ste kód naformátovali spôsobom Go, ako je vysvetlené v publikáciu Effective Go od tímu Go na dosiahnutie najlepších výsledkov.

Tu je príklad použitia jednoriadkových komentárov v štýle C++:

// User je struct model obsahujúci
typu Používateľ štrukturovať {
}

Môžete tiež použiť komentáre bloku v štýle C:

/* 
Používateľ je prispôsobená dátová štruktúra
Tu môžete zahrnúť akýkoľvek text a server Godoc ho pri spustení naformátuje.
*/
typu Používateľ štrukturovať {
}

Vo vyššie uvedených komentároch „Používateľ“ začína vety, pretože komentár popisuje, čo robí štruktúra používateľa. Toto je jedna z mnohých tém, o ktorých hovorí Go way. Začínať dokumentačné vety užitočným názvom je kľúčové, pretože prvá veta sa nachádza v zozname balíkov.

Spustenie servera Godoc

Keď zakomentujete svoj kód, môžete spustiť godoc príkaz vo vašom termináli z adresára kódu vášho projektu.

Vývojári Go zvyčajne používajú port 6060 hostiť dokumentáciu. Toto je príkaz na spustenie servera Godoc na tomto porte:

godoc -http=:6060

Vyššie uvedený príkaz hostí dokumentáciu vášho kódu na localhost alebo 127.0.0.1. Port nemusí byť 6060; godoc pobeží na akomkoľvek neobsadenom porte. Vždy je však najlepšie dodržiavať pravidlá dokumentácie Go.

Po spustení príkazu si dokumentáciu môžete pozrieť v prehliadači na stránke localhost: 6060. Čas, ktorý Godoc potrebuje na vytvorenie vašej dokumentácie, bude závisieť od jej veľkosti a zložitosti.

Nižšie uvedený kód sa drží spôsobu Go, v tomto prípade pomocou jednoriadkových komentárov.

// názov balíka
balík užívateľ
// fmt je zodpovedný za formátovanie
importovať (
 "fmt"
)


// Používateľ je štruktúra ľudských údajov
typu Používateľ štrukturovať {
 Vek int
 názov reťazec
}


funchlavné() {
// človek je inicializácia štruktúry používateľa
 človek := Používateľ {
 Vek: 0,
 Meno: "osoba",
 }


fmt. Println (človek. Rozprávať ())
}
// Talk je metóda používateľskej štruktúry
func(používateľ prijímača)Hovorte()reťazec {
vrátiť "Každý používateľ musí niečo povedať!"
}

Ak spustíte Godoc na kódovom module vyššie, mali by ste vidieť výstup vyzerať takto:

Všimnite si, že je v známom formáte, podobnom tomu, ktorý nájdete na oficiálnej webovej stránke dokumentácie Go.

Godoc používa komentár pred deklaráciou balíka ako Prehľad. Uistite sa, že tento komentár popisuje, čo váš program robí.

The Index obsahuje odkazy na deklarácie typu a metódy, takže k nim môžete rýchlo prejsť.

Godoc tiež poskytuje funkcie na prezeranie zdrojového kódu, ktorý tvorí balík v Súbory balíkov oddiele.

Zlepšenie dokumentácie pomocou Godoc

Do svojej dokumentácie Godoc môžete zahrnúť viac než len obyčajný text. Môžete pridať adresy URL, na ktoré bude Godoc generovať odkazy a štruktúrovať vaše komentáre do odsekov.

Ak chcete odkazovať na zdroj, napíšte URL do svojho komentára a Godoc to rozpozná a pridá odkaz. Pre odseky nechajte prázdny riadok komentára.

// Hlavný balík
balík hlavné
// Dokument predstavuje bežný dokument.
//
// Odkaz na https://google.com
typu dokument štrukturovať {
 stránky int
 referencie reťazec
 podpísaný bool
}


// Write zapíše nový dokument do úložiska
//
// O písaní sa môžete dozvedieť z Wikipedia.com
funcNapíšte() {
}

Upozorňujeme, že Godoc vyžaduje, aby ste napísali úplné adresy URL, aby ich mohol prepojiť. V tomto príklade adresa URL Google obsahuje https:// prefix, takže Godoc naň pridá odkaz. Keďže doména Wikipedia nie je sama o sebe úplnou URL, Godoc ju nechá tak.

Tu je niekoľko najlepších zásad, ktoré by ste mali použiť pri dokumentovaní kódu Go:

  • Udržujte svoju dokumentáciu jednoduchú a stručnú.
  • Vetu funkcií, typov a deklarácií premenných začnite ich názvami.
  • Začnite riadok odsadením, aby ste ho vopred naformátovali ako kód.
  • Komentáre začínajúce „CHRÁBA (meno)“ ako „CHRÁBA (joe): Toto nefunguje“ sú špeciálne. Godoc ich rozpozná ako chyby a nahlási ich vo vlastnej sekcii dokumentácie.

Godoc vám pomôže s dokumentáciou

Pomocou Godoc môžete byť produktívnejší a menej sa starať o ručnú dokumentáciu programov.

Svoju dokumentáciu by ste mali udržiavať presnú, podrobnú a do bodky, aby ju vaša cieľová skupina ľahšie čítala a porozumela. Pri úprave programu je tiež dôležité, aby ste komentáre ku kódu aktualizovali.

Pozrite si dokumentáciu balíka Godoc, kde sa dozviete viac o používaní Godoc.