Domājot par programmēšanu, ir dabiski koncentrēties uz tādām tēmām kā valodas, algoritmi un atkļūdošana. Taču tehniskā dokumentācija var būt tikpat svarīga, lai to izdarītu pareizi.
Bez labas dokumentācijas var ciest koda atkārtota izmantošana. Lietotāji, kuri ir jauni kodu bāzē, var viegli pazust vai sarūgtināt, ja dokumentācija nav līdz nullei. Ir svarīgi ne tikai saprast, ko programma dara, bet arī to, kā vai pat kāpēc tā to dara.
Tādas pakotnes kā Pydoc for Python un Javadoc for Java palīdz automatizēt procesa daļu. Godoc rīks dara to pašu Go.
Kas ir Godoks?
Godoc ir Go pakotne, kas ļauj izveidot, pārvaldīt un izmantot Go dokumentāciju “go veidā”. Go way ir principu kopums, kas jums kā Go programmētājam ir jāievēro, lai uzlabotu koda kvalitāti.
Izmantojot Godoc, varat viegli lasīt citu izstrādātāju dokumentāciju un kodu. Varat arī automatizēt savas dokumentācijas izveidi un publicēt to, izmantojot Godoc.
Godoks ir līdzīgs Javadoc, Java koda dokumentētājs. Viņi abi izmanto komentārus un kodu moduļos, lai izveidotu dokumentāciju. Un abi rīki strukturē šo dokumentāciju HTML formātā, lai jūs to varētu skatīt pārlūkprogrammā.
Darba sākšana ar Godoc
Godoc lietošana ir vienkārša. Lai sāktu, instalējiet Godoc pakotni no golang vietnes, izmantojot šo komandu:
aiziet iegūstiet golang.org/x/tools/cmd/godoc
Palaižot šo komandu, Godoc tiks instalēts jūsu norādītajā darbvietā. Kad tas ir pabeigts, jums vajadzētu būt iespējai palaist godoks komanda terminālī. Ja instalācijā ir radušās kļūdas, mēģiniet atjaunināt Pāriet uz jaunāko versiju.
Godoc meklē vienas un vairāku rindiņu komentārus, ko iekļaut tā ģenerētajā dokumentācijā.
Noteikti formatējiet kodu Go veidā, kā paskaidrots publikācija Effective Go Go komanda, lai sasniegtu labākos rezultātus.
Tālāk ir sniegts piemērs, izmantojot C++ stila vienas rindiņas komentārus:
// Lietotājs ir struktūras modelis, kas satur
veids Lietotājs struktūra {
}
Varat arī izmantot C stila bloku komentārus:
/*
Lietotājs ir pielāgota datu struktūraŠeit varat iekļaut jebkuru tekstu, un Godoc serveris to formatēs, kad to palaižat.
*/
veids Lietotājs struktūra {
}
Iepriekš esošajos komentāros “Lietotājs” sāk teikumus, jo komentārs apraksta lietotāja struktūras darbību. Šī ir viena no daudzajām tēmām, ko apspriež Go way. Ir ļoti svarīgi sākt dokumentācijas teikumus ar noderīgu nosaukumu, jo pirmais teikums parādās pakotņu sarakstā.
Godoc servera darbināšana
Kad esat komentējis savu kodu, varat palaist godoks komandu savā terminālī no sava projekta kodu direktorijas.
Parasti Go izstrādātāji izmanto portu 6060 lai uzņemtu dokumentāciju. Šī ir komanda Godoc servera palaišanai šajā portā:
godoc -http=:6060
Iepriekš esošā komanda mitina jūsu koda dokumentāciju localhost vai 127.0.0.1. Portam nav jābūt 6060; godoc darbosies jebkurā neaizņemtā ostā. Tomēr vienmēr vislabāk ir ievērot Go dokumentācijas noteikumus.
Kad esat palaidis komandu, varat skatīt savu dokumentāciju pārlūkprogrammā, apmeklējot vietni vietējais saimnieks: 6060. Laiks, kas nepieciešams Godoc dokumentācijas ģenerēšanai, būs atkarīgs no tās lieluma un sarežģītības.
Tālāk norādītais kods atbilst Go veidam, šajā gadījumā izmantojot vienas rindiņas komentārus.
// iepakojuma nosaukums
iepakojums lietotājs// fmt ir atbildīgs par formatēšanu
imports (
"fmt"
)// Lietotājs ir cilvēka datu struktūra
veids Lietotājs struktūra {
Vecums starpt
Vārds virkne
}funcgalvenais() {
// cilvēks ir lietotāja struktūras inicializācija
cilvēks := Lietotājs {
Vecums: 0,
Vārds: "persona",
}fmt. Println (cilvēks. Runāt())
}
// Talk ir Lietotāja struktūras metode
func(uztvērēja lietotājs)Runājiet()virkne {
atgriezties "Katrs lietotājs var kaut ko pateikt!"
}
Ja palaižat Godoc iepriekš minētajā koda modulī, izvadei vajadzētu izskatīties apmēram šādi:
Ņemiet vērā, ka tas ir pazīstamā formātā, līdzīgs tam, ko atradīsit Go oficiālajā dokumentācijas vietnē.
Godoc izmanto komentāru pirms iepakojuma deklarācijas kā Pārskats. Pārliecinieties, vai šis komentārs apraksta jūsu programmas darbību.
The Indekss satur saites uz tipu deklarācijām un metodēm, lai jūs varētu ātri pārvietoties uz tām.
Godoc nodrošina arī funkcionalitāti, lai skatītu avota kodu, kas veido pakotni Pakotņu faili sadaļā.
Dokumentācijas uzlabošana, izmantojot Godoc
Godoc dokumentācijā varat iekļaut ne tikai vienkāršu tekstu. Varat pievienot vietrāžus URL, kuriem Godoc ģenerēs saites, un strukturēs jūsu komentārus rindkopās.
Ja vēlaties izveidot saiti uz kādu resursu, komentārā ierakstiet URL, un Godoc to atpazīs un pievienos saiti. Rindkopām atstājiet tukšu komentāra rindiņu.
// Pakas galvenā
iepakojums galvenais// Dokuments ir parasts dokuments.
//
// Saite uz https://google.com
veids Dokuments struktūra {
lapas starpt
atsauces virkne
parakstīts bool
}// Write ieraksta krātuvē jaunu dokumentu
//
// Jūs varat uzzināt par rakstīšanu vietnē Wikipedia.com
funcRakstiet() {
}
Ņemiet vērā, ka Godoc pieprasa pilnībā izrakstīt vietrāžus URL, lai tas varētu tos saistīt. Šajā piemērā Google URL ietver https:// prefiksu, tāpēc Godoks pievieno tam saiti. Tā kā Wikipedia domēns pats par sevi nav pilns URL, Godoc to atstās vienu.
Šeit ir daži labākie principi, kas jāievēro, dokumentējot savu Go kodu.
- Saglabājiet savu dokumentāciju vienkāršu un kodolīgu.
- Sāciet teikumu par funkcijām, veidiem un mainīgo deklarācijām ar to nosaukumiem.
- Sāciet rindu ar atkāpi, lai to iepriekš formatētu kā kodu.
- Komentāri, kas sākas ar "BUG(nosaukums)", piemēram, "BUG(joe): Tas nedarbojas", ir īpaši. Godoc atpazīs tās kā kļūdas un ziņos par tām savā dokumentācijas sadaļā.
Godoks var atvieglot jūsu dokumentēšanas problēmas
Izmantojot Godoc, jūs varat būt produktīvāks un mazāk jāuztraucas par programmu dokumentēšanu ar roku.
Dokumentācijai jābūt precīzai, detalizētai un precīzai, lai mērķauditorijai to būtu vieglāk lasīt un saprast. Ir arī svarīgi, lai koda komentāri būtu atjaunināti, kad veicat izmaiņas programmā.
Apskatiet Godoc pakotnes dokumentāciju, lai uzzinātu vairāk par Godoc lietošanu.