Când te gândești la programare, este firesc să te concentrezi pe subiecte precum limbaje, algoritmi și depanare. Dar documentația tehnică poate fi la fel de importantă pentru a fi corectă.

Fără o documentare bună, reutilizarea codului poate avea de suferit. Utilizatorii nou la o bază de cod se pot pierde cu ușurință sau frustrați dacă documentația nu este la îndemână. Nu este important doar să înțelegeți ce face un program, ci și cum – sau chiar de ce – îl face.

Pachete precum Pydoc pentru Python și Javadoc pentru Java ajută prin automatizarea unei părți a procesului. Instrumentul Godoc face același lucru pentru Go.

Ce este Godoc?

Godoc este un pachet Go care vă permite să creați, să gestionați și să utilizați documentația Go în „modul Go”. Modul Go este un set de principii pe care, în calitate de programator Go, ar trebui să le urmați pentru a îmbunătăți calitatea codului.

Folosind Godoc, puteți citi cu ușurință documentația și codul altor dezvoltatori. De asemenea, puteți automatiza crearea propriei documentații și o puteți publica folosind Godoc.

Godoc este asemănător cu Javadoc, documentarul de cod pentru Java. Ambii folosesc comentarii și cod în module pentru a genera documentație. Și ambele instrumente structurează această documentație în HTML, astfel încât să o puteți vizualiza într-un browser.

Noțiuni introductive cu Godoc

Utilizarea Godoc este ușoară. Pentru a începe, instalați pachetul Godoc de pe site-ul golang folosind această comandă:

merge obține golang.org/x/tools/cmd/godoc

Rularea acestei comenzi va instala Godoc în spațiul de lucru specificat. Odată ce se încheie, ar trebui să puteți rula godoc comandă într-un terminal. Dacă există erori la instalarea dvs., încercați să actualizați Go la o versiune recentă.

Godoc caută comentarii cu o singură linie și mai multe rânduri pentru a le include în documentația pe care o generează.

Asigurați-vă că formatați codul în modul Go, așa cum este explicat în publicația Effective Go de echipa Go pentru cele mai bune rezultate.

Iată un exemplu de utilizare a comentariilor într-o singură linie în stil C++:

// User este un model struct care conține
tip Utilizator struct {
}

Puteți utiliza, de asemenea, comentarii de bloc în stil C:

/* 
Utilizatorul este o structură de date personalizată
Puteți include orice text aici și serverul Godoc îl va formata când îl rulați.
*/
tip Utilizator struct {
}

În comentariile de mai sus, „Utilizator” începe propozițiile deoarece comentariul descrie ceea ce face structura utilizatorului. Acesta este unul dintre multele subiecte pe care le discută modul Go. Începerea propozițiilor de documentare cu un nume util este crucială, deoarece prima propoziție apare în lista de pachete.

Rularea unui server Godoc

După ce ați comentat codul, puteți rula godoc comanda în terminalul dvs., din directorul de cod al proiectului.

În mod convențional, dezvoltatorii Go folosesc portul 6060 pentru a găzdui documentația. Aceasta este comanda pentru rularea unui server Godoc pe acel port:

godoc -http=:6060

Comanda de mai sus găzduiește documentația de cod localhost sau 127.0.0.1. Portul nu trebuie să fie 6060; godoc va rula pe orice port neocupat. Cu toate acestea, este întotdeauna cel mai bine să urmați convențiile de documentare Go.

După ce ați rulat comanda, puteți vizualiza documentația într-un browser vizitând gazdă locală: 6060. Timpul necesar Godoc pentru a vă genera documentația va depinde de dimensiunea și complexitatea acesteia.

Codul de mai jos aderă la modul Go, în acest caz folosind comentarii pe o singură linie.

// numele pachetului
pachet utilizator
// fmt este responsabil pentru formatare
import (
 "fmt"
)


// Utilizatorul este o structură de date umane
tip Utilizator struct {
 Vârstă int
 Nume şir
}


funcprincipal() {
// uman este o inițializare a structurii User
 uman := Utilizator {
 Vârstă: 0,
 Nume: „persoană”,
 }


fmt. Println (uman. Vorbi())
}
// Talk este o metodă a structurii User
func(Utilizator receptor)Vorbi()şir {
întoarcere „Fiecare utilizator poate spune ceva!”
}

Dacă rulați Godoc pe modulul de cod de mai sus, ar trebui să vedeți rezultatul care arată cam așa:

Observați că este într-un format familiar, similar cu ceea ce veți găsi pe site-ul web oficial de documentație Go.

Godoc folosește comentariul care precede declarația pachetului ca Prezentare generală. Asigurați-vă că acest comentariu descrie ceea ce face programul dvs.

The Index conține link-uri către declarațiile de tip și metodele, astfel încât să puteți naviga rapid la ele.

Godoc oferă, de asemenea, funcționalitate pentru vizualizarea codului sursă care alcătuiește pachetul în Fișiere pachet secțiune.

Îmbunătățirea documentației folosind Godoc

Puteți include mai mult decât text simplu în documentația Godoc. Puteți adăuga adrese URL pentru care Godoc va genera link-uri și vă va structura comentariile în paragrafe.

Dacă doriți să conectați la o resursă, scrieți adresa URL în comentariul dvs., iar Godoc o va recunoaște și va adăuga un link. Pentru paragrafe, lăsați o linie de comentarii goală.

// Pachetul principal
pachet principal
// Documentul reprezintă un document obișnuit.
//
// Link către https://google.com
tip Document struct {
 pagini int
 referințe şir
 semnat bool
}


// Write scrie un document nou în stocare
//
// Puteți afla despre scriere de pe Wikipedia.com
funcScrie() {
}

Rețineți că Godoc vă solicită să scrieți adresele URL în întregime pentru a le lega. În acest exemplu, adresa URL Google include https:// prefix, așa că Godoc adaugă un link la acesta. Deoarece domeniul Wikipedia nu este o adresă URL completă în sine, Godoc îl va lăsa în pace.

Iată câteva dintre cele mai bune principii pe care să le aplicați atunci când vă documentați codul Go:

  • Păstrați documentația simplă și concisă.
  • Începeți propoziția de funcții, tipuri și declarații de variabile cu numele lor.
  • Începeți o linie cu o indentare pentru a o preformata ca cod.
  • Comentariile care încep cu „BUG(nume)” precum „BUG(joe): Acest lucru nu funcționează” sunt speciale. Godoc le va recunoaște ca erori și le va raporta în propria secțiune a documentației.

Godoc vă poate ușura problemele de documentare

Folosind Godoc, puteți fi mai productiv și vă puteți îngrijora mai puțin cu privire la efortul de a vă documenta manual programele.

Ar trebui să păstrați documentația precisă, detaliată și la obiect pentru a facilita citirea și înțelegerea publicului țintă. De asemenea, este esențial să păstrați la zi comentariile de cod pe măsură ce vă modificați programul.

Consultați documentația pachetului Godoc pentru a afla mai multe despre utilizarea Godoc.