Kai galvojate apie programavimą, natūralu, kad sutelkite dėmesį į tokias temas kaip kalbos, algoritmai ir derinimas. Tačiau techninė dokumentacija gali būti lygiai tokia pat svarbi, kad būtų tinkamai sutvarkyta.
Be geros dokumentacijos gali nukentėti kodo pakartotinis naudojimas. Nauji kodų bazės naudotojai gali lengvai pasiklysti arba nusivilti, jei dokumentacija nėra iki nulio. Svarbu ne tik suprasti, ką programa daro, bet ir kaip – ar net kodėl – ji tai daro.
Tokie paketai kaip Pydoc for Python ir Javadoc for Java padeda automatizuoti dalį proceso. „Godoc“ įrankis atlieka tą patį „Go“.
Kas yra Godokas?
„Godoc“ yra „Go“ paketas, leidžiantis kurti, tvarkyti ir naudoti „Go“ dokumentaciją „go būdu“. „Go way“ yra principų rinkinys, kurio, kaip „Go“ programuotojas, turėtumėte laikytis norėdami pagerinti kodo kokybę.
Naudodami Godoc galite lengvai perskaityti kitų kūrėjų dokumentus ir kodą. Taip pat galite automatizuoti savo dokumentacijos kūrimą ir paskelbti ją naudodami „Godoc“.
Godokas yra panašus į
Javadoc, kodo dokumentatorius, skirtas Java. Jie abu naudoja komentarus ir kodą moduliuose, kad sukurtų dokumentus. Ir abu įrankiai sudaro dokumentaciją HTML formatu, kad galėtumėte peržiūrėti juos naršyklėje.Darbo su Godoc pradžia
„Godoc“ naudojimas yra paprastas. Norėdami pradėti, įdiekite „Godoc“ paketą iš „golang“ svetainės naudodami šią komandą:
eik gaukite golang.org/x/tools/cmd/godoc
Vykdydami šią komandą, „Godoc“ bus įdiegta jūsų nurodytoje darbo vietoje. Kai jis bus baigtas, turėtumėte galėti paleisti godokas komanda terminale. Jei įdiegiant yra kokių nors klaidų, pabandykite atnaujinti Eikite į naujausią versiją.
„Godoc“ ieško vienos ir kelių eilučių komentarų, kuriuos galima įtraukti į savo sukurtus dokumentus.
Įsitikinkite, kad kodą suformatavote taip, kaip paaiškinta leidinys „Efektyvus eik“. Go komanda siekdama geriausių rezultatų.
Štai C++ stiliaus vienos eilutės komentarų naudojimo pavyzdys:
// Vartotojas yra struktūros modelis, kuriame yra
tipo Vartotojas struktūra {
}
Taip pat galite naudoti C stiliaus blokų komentarus:
/*
Vartotojas yra tinkinta duomenų struktūraČia galite įtraukti bet kokį tekstą ir „Godoc“ serveris jį suformatuos, kai jį paleisite.
*/
tipo Vartotojas struktūra {
}
Aukščiau pateiktuose komentaruose „Vartotojas“ pradeda sakinius, nes komentare aprašoma, ką daro vartotojo struktūra. Tai viena iš daugelio temų, kurias aptaria „Go būdas“. Labai svarbu pradėti dokumentų sakinius naudingu pavadinimu, nes paketų sąraše pasirodo pirmasis sakinys.
„Godoc“ serverio paleidimas
Kai pakomentuosite savo kodą, galite paleisti godokas komandą savo terminale iš projekto kodų katalogo.
Paprastai „Go“ kūrėjai naudoja prievadą 6060 priimti dokumentus. Tai komanda, skirta paleisti Godoc serverį tame prievade:
godoc -http=:6060
Aukščiau pateikta komanda talpina jūsų kodo dokumentus localhost arba 127.0.0.1. Prievadas neturi būti 6060; godoc veiks bet kuriame neužimtame uoste. Tačiau visada geriausia laikytis „Go“ dokumentacijos taisyklių.
Paleidę komandą, galite peržiūrėti savo dokumentus naršyklėje apsilankę Localhost: 6060. Laikas, per kurį Godoc sugeneruos jūsų dokumentaciją, priklausys nuo jos dydžio ir sudėtingumo.
Žemiau pateiktas kodas atitinka „Eiti“ būdą, šiuo atveju naudojant vienos eilutės komentarus.
// paketo pavadinimas
paketą Vartotojas// fmt atsakingas už formatavimą
importuoti (
"fmt"
)// Vartotojas yra žmogaus duomenų struktūra
tipo Vartotojas struktūra {
Amžius tarpt
vardas styga
}funcpagrindinis() {
// žmogus yra vartotojo struktūros inicijavimas
žmogus := Vartotojas {
Amžius: 0,
Vardas: "asmuo",
}fmt. Println (žmogus. Kalbėtis ()
}
// Kalbėjimas yra vartotojo struktūros metodas
func(imtuvo vartotojas)Kalbėk()styga {
grąžinti "Kiekvienas vartotojas turi ką nors pasakyti!"
}
Jei paleidžiate „Godoc“ aukščiau esančiame kodo modulyje, išvestis turėtų atrodyti maždaug taip:
Atkreipkite dėmesį, kad jis yra žinomo formato, panašus į tai, ką rasite oficialioje „Go“ dokumentų svetainėje.
Godoc naudoja komentarą prieš pakuotės deklaraciją kaip Apžvalga. Įsitikinkite, kad šis komentaras apibūdina jūsų programos veiklą.
The Indeksas yra nuorodų į tipo deklaracijas ir metodus, kad galėtumėte greitai juos naršyti.
„Godoc“ taip pat suteikia galimybę peržiūrėti šaltinio kodą, sudarantį paketą Paketo failai skyrius.
Dokumentacijos tobulinimas naudojant Godoc
Į „Godoc“ dokumentus galite įtraukti ne tik paprastą tekstą. Galite pridėti URL, kuriems „Godoc“ sukurs nuorodas, ir suskirstys jūsų komentarus į pastraipas.
Jei norite susieti su šaltiniu, komentare parašykite URL, o Godoc jį atpažins ir pridės nuorodą. Pastraipoms palikite tuščią komentaro eilutę.
// Paketo pagrindinis
paketą pagrindinis// Dokumentas yra įprastas dokumentas.
//
// Nuoroda į https://google.com
tipo dokumentas struktūra {
puslapių tarpt
nuorodos styga
pasirašė bool
}// Write įrašo į saugyklą naują dokumentą
//
// Apie rašymą galite sužinoti iš Wikipedia.com
funcRašyti() {
}
Atminkite, kad „Godoc“ reikalauja, kad išrašytumėte visus URL, kad būtų galima juos susieti. Šiame pavyzdyje „Google“ URL apima https:// priešdėlį, todėl Godokas prideda prie jo nuorodą. Kadangi Vikipedijos domenas nėra visas URL, Godokas paliks jį ramybėje.
Štai keletas geriausių principų, kurių reikia laikytis dokumentuojant „Go“ kodą:
- Pateikite savo dokumentus paprastus ir glaustus.
- Pradėkite funkcijų, tipų ir kintamųjų deklaracijų sakinį jų pavadinimais.
- Pradėkite eilutę įtrauka, kad iš anksto suformatuotumėte ją kaip kodą.
- Komentarai, prasidedantys „BUG(vardas)“, pvz., „BUG(joe): Tai neveikia“, yra ypatingi. Godoc atpažins jas kaip klaidas ir praneš apie jas savo dokumentacijos skyriuje.
„Godoc“ gali palengvinti jūsų dokumentų bėdas
Naudodami Godoc galite būti produktyvesni ir mažiau nerimauti dėl pastangų dokumentuoti programas ranka.
Turite turėti tikslius, išsamius ir tikslius dokumentus, kad tikslinei auditorijai būtų lengviau skaityti ir suprasti. Taip pat labai svarbu, kad modifikuodami programą nuolat atnaujintumėte kodo komentarus.
Peržiūrėkite „Godoc“ paketo dokumentaciją, kad sužinotumėte daugiau apie „Godoc“ naudojimą.