Kun ajattelet ohjelmointia, on luonnollista keskittyä aiheisiin, kuten kieliin, algoritmeihin ja virheenkorjaukseen. Mutta tekniset asiakirjat voivat olla yhtä tärkeitä, jotta ne saadaan oikein.
Ilman hyvää dokumentaatiota koodin uudelleenkäytettävyys voi kärsiä. Koodikannan uudet käyttäjät voivat helposti eksyä tai turhautua, jos dokumentaatio ei ole aivan tyhjä. Ei ole tärkeää vain ymmärtää, mitä ohjelma tekee, vaan myös kuinka – tai jopa miksi – se tekee sen.
Paketit, kuten Pydoc for Python ja Javadoc for Java auttavat automatisoimalla osan prosessista. Godoc-työkalu tekee samoin Golle.
Mikä Godoc on?
Godoc on Go-paketti, jonka avulla voit luoda, hallita ja käyttää Go-dokumentaatiota "Go-tavalla". Go way on joukko periaatteita, joita Go-ohjelmoijana sinun tulee noudattaa koodin laadun parantamiseksi.
Godocin avulla voit helposti lukea muiden kehittäjien dokumentaatiota ja koodia. Voit myös automatisoida oman dokumentaation luomisen ja julkaista sen Godocin avulla.
Godoc on samanlainen kuin
Javadoc, Java-koodidokumentaattori. Molemmat käyttävät kommentteja ja koodia moduuleissa dokumentaation luomiseen. Ja molemmat työkalut jäsentävät dokumentaation HTML-muodossa, jotta voit tarkastella sitä selaimessa.Godocin käytön aloittaminen
Godocin käyttö on helppoa. Aloita asentamalla Godoc-paketti golang-verkkosivustolta tällä komennolla:
mennä hanki golang.org/x/tools/cmd/godoc
Tämän komennon suorittaminen asentaa Godocin määritettyyn työtilaan. Kun se on valmis, sinun pitäisi pystyä suorittamaan goddoc komento terminaalissa. Jos asennuksessa on virheitä, yritä päivittää Siirry uusimpaan versioon.
Godoc etsii yksi- ja monirivisiä kommentteja sisällytettäväksi luomaansa dokumentaatioon.
Varmista, että muotoilet koodin Go-tavalla, kuten kohdassa selitetään Effective Go -julkaisu Go-tiimin toimesta parhaiden tulosten saavuttamiseksi.
Tässä on esimerkki C++-tyylisistä yksirivisistä kommenteista:
// Käyttäjä on rakennemalli, joka sisältää
tyyppi Käyttäjä struct {
}
Voit myös käyttää C-tyylisiä lohkokommentteja:
/*
Käyttäjä on mukautettu tietorakenneVoit sisällyttää tähän mitä tahansa tekstiä ja Godoc-palvelin muotoilee sen, kun suoritat sen.
*/
tyyppi Käyttäjä struct {
}
Yllä olevissa kommenteissa "Käyttäjä" aloittaa lauseet, koska kommentti kuvaa, mitä käyttäjärakenne tekee. Tämä on yksi monista aiheista, joita Go way käsittelee. Dokumentaation lauseiden aloittaminen hyödyllisellä nimellä on tärkeää, koska ensimmäinen lause näkyy pakettiluettelossa.
Godoc-palvelimen käyttäminen
Kun olet kommentoinut koodiasi, voit suorittaa sen goddoc komento päätteessäsi, projektisi koodihakemistosta.
Perinteisesti Go-kehittäjät käyttävät porttia 6060 isännöidä asiakirjoja. Tämä on komento Godoc-palvelimen ajamiseen kyseisessä portissa:
godoc -http=:6060
Yllä oleva komento isännöi koodidokumentaatiota localhost tai 127.0.0.1. Portin ei tarvitse olla 6060; godoc toimii missä tahansa vapaassa portissa. On kuitenkin aina parasta noudattaa Go-dokumentaatiokäytäntöjä.
Kun olet suorittanut komennon, voit tarkastella dokumentaatiota selaimessa käymällä osoitteessa paikallinen isäntä: 6060. Aika, jonka Godoc vie dokumentaation luomiseen, riippuu sen koosta ja monimutkaisuudesta.
Alla oleva koodi noudattaa Go-tapaa, tässä tapauksessa käyttämällä yksirivisiä kommentteja.
// paketin nimi
paketti käyttäjä// fmt vastaa muotoilusta
tuonti (
"fmt"
)// Käyttäjä on ihmisdatan rakenne
tyyppi Käyttäjä struct {
Ikä int
Nimi merkkijono
}funcpää() {
// ihminen on User-rakenteen alustus
ihminen := Käyttäjä {
Ikä: 0,
Nimi: "henkilö",
}fmt. Println (ihminen. Puhua())
}
// Talk on User-rakenteen menetelmä
func(vastaanottava käyttäjä)Puhua()merkkijono {
palata "Jokainen käyttäjä saa sanoa jotain!"
}
Jos suoritat Godocin yllä olevassa koodimoduulissa, tulosteen pitäisi näyttää tältä:
Huomaa, että se on tutussa muodossa, joka on samanlainen kuin Go-virallisilla dokumentaatiosivustoilla.
Godoc käyttää paketin ilmoitusta edeltävää kommenttia Yleiskatsaus. Varmista, että tämä kommentti kuvaa mitä ohjelmasi tekee.
The Indeksi sisältää linkkejä tyyppimäärityksiin ja menetelmiin, jotta voit navigoida niihin nopeasti.
Godoc tarjoaa myös toiminnot paketin muodostavan lähdekoodin katseluun Pakettitiedostot -osio.
Dokumentoinnin parantaminen Godocin avulla
Voit sisällyttää Godoc-dokumentaatioosi muutakin kuin pelkkää tekstiä. Voit lisätä URL-osoitteita, joille Godoc luo linkit ja jäsentää kommenttisi kappaleiksi.
Jos haluat linkittää resurssiin, kirjoita URL-osoite kommenttiisi, niin Godoc tunnistaa sen ja lisää linkin. Kappaleiden kohdalla jätä tyhjä kommenttirivi.
// Paketin pää
paketti pää// Asiakirja edustaa tavallista asiakirjaa.
//
// Linkki https://google.com
tyyppi Asiakirja struct {
sivuja int
viittauksia merkkijono
allekirjoitettu bool
}// Write kirjoittaa uuden asiakirjan tallennustilaan
//
// Voit oppia kirjoittamisesta osoitteesta Wikipedia.com
funcKirjoittaa() {
}
Huomaa, että Godoc edellyttää, että kirjoitat URL-osoitteet kokonaisuudessaan, jotta se voi linkittää ne. Tässä esimerkissä Googlen URL-osoite sisältää https:// etuliite, joten Godoc lisää linkin siihen. Koska Wikipedia-verkkotunnus ei ole yksinään täydellinen URL-osoite, Godoc jättää sen rauhaan.
Tässä on joitain parhaita periaatteita Go-koodin dokumentoinnissa:
- Pidä dokumentaatiosi yksinkertaisena ja ytimekkäänä.
- Aloita funktioiden, tyyppien ja muuttujamäärittelyjen lause niiden nimillä.
- Aloita rivi sisennyksellä muotoillaksesi sen valmiiksi koodiksi.
- Kommentit, jotka alkavat "BUG(nimi)" kuten "BUG(joe): Tämä ei toimi" ovat erityisiä. Godoc tunnistaa ne bugeiksi ja ilmoittaa niistä omassa dokumentaatiossaan.
Godoc voi helpottaa dokumentointiongelmiasi
Godocin avulla voit olla tuottavampi ja vähemmän huolissasi ohjelmien käsin dokumentoinnista.
Sinun tulee pitää dokumentaatiosi täsmällisenä, yksityiskohtaisena ja täsmällisenä, jotta kohdeyleisösi on helpompi lukea ja ymmärtää. On myös erittäin tärkeää, että pidät koodin kommentit ajan tasalla, kun muokkaat ohjelmaa.
Katso Godoc-paketin dokumentaatio saadaksesi lisätietoja Godocin käytöstä.
