Quando si pensa alla programmazione, è naturale concentrarsi su argomenti come linguaggi, algoritmi e debug. Ma la documentazione tecnica può essere altrettanto importante per essere corretta.

Senza una buona documentazione, la riutilizzabilità del codice può risentirne. Gli utenti che non conoscono una base di codice possono facilmente perdersi o essere frustrati se la documentazione non è all'altezza. Non è solo importante capire cosa fa un programma, ma come, o anche perché, lo fa.

Pacchetti come Pydoc per Python e Javadoc per Java aiutano automatizzando parte del processo. Lo strumento Godoc fa lo stesso per Go.

Cos'è Godoc?

Godoc è un pacchetto Go che ti consente di creare, gestire e utilizzare la documentazione Go in "modo Go". Il metodo Go è un insieme di principi che, come programmatore Go, dovresti seguire per migliorare la qualità del codice.

Usando Godoc, puoi leggere facilmente la documentazione e il codice di altri sviluppatori. Puoi anche automatizzare la creazione della tua documentazione e pubblicarla utilizzando Godoc.

instagram viewer

Godoc è simile a Javadoc, il documentatore di codice per Java. Entrambi usano commenti e codice nei moduli per generare documentazione. Ed entrambi gli strumenti strutturano la documentazione in HTML in modo da poterla visualizzare in un browser.

Iniziare con Godoc

Usare Godoc è facile. Per iniziare, installa il pacchetto Godoc dal sito web di Golang usando questo comando:

andare ottenere golang.org/x/tools/cmd/godoc

L'esecuzione di questo comando installerà Godoc nell'area di lavoro specificata. Una volta completato, dovresti essere in grado di eseguire il godoc comando in un terminale. Se si verificano errori con l'installazione, prova ad aggiornare Vai a una versione recente.

Godoc cerca commenti a riga singola e multipla da includere nella documentazione che genera.

Assicurati di formattare il codice nel modo Go, come spiegato in la pubblicazione Effective Go dal team Go per i migliori risultati.

Ecco un esempio di utilizzo di commenti a riga singola in stile C++:

// L'utente è un modello struct contenente
genere Utente struttura {
}

Puoi anche usare i commenti di blocco in stile C:

/* 
L'utente è una struttura di dati personalizzata
Puoi includere qualsiasi testo qui e il server Godoc lo formatterà quando lo esegui.
*/
genere Utente struttura {
}

Nei commenti sopra, "Utente" inizia le frasi perché il commento descrive ciò che fa la struttura Utente. Questo è uno dei tanti argomenti trattati dal modo di andare. Avviare frasi di documentazione con un nome utile è fondamentale poiché la prima frase appare nell'elenco dei pacchetti.

Esecuzione di un server Godoc

Dopo aver commentato il codice, è possibile eseguire il godoc comando nel tuo terminale, dalla directory del codice del tuo progetto.

Convenzionalmente, gli sviluppatori Go usano port 6060 per ospitare la documentazione. Questo è il comando per eseguire un server Godoc su quella porta:

godoc -http=:6060

Il comando sopra ospita la documentazione del tuo codice localhost o 127.0.0.1. La porta non deve essere 6060; godoc funzionerà su qualsiasi porta non occupata. Tuttavia, è sempre meglio seguire le convenzioni della documentazione Go.

Una volta eseguito il comando, puoi visualizzare la documentazione in un browser visitando il sito host locale: 6060. Il tempo impiegato da Godoc per generare la tua documentazione dipenderà dalle sue dimensioni e complessità.

Il codice seguente aderisce al metodo Go, in questo caso utilizzando commenti a riga singola.

// nome del pacchetto
pacchetto utente
// fmt è responsabile della formattazione
importare (
 "fmt"
)


// L'utente è una struttura di dati umani
genere Utente struttura {
 Età int
 Nome corda
}


funzprincipale() {
// human è un'inizializzazione della User struct
 umano := Utente {
 Età: 0,
 Nome: "persona",
 }


fmt. Println (umano. Parlare())
}
// Talk è un metodo della struttura User
funz(Utente ricevente)Parlare()corda {
Restituzione "Ogni utente può dire qualcosa!"
}

Se esegui Godoc sul modulo di codice sopra, dovresti vedere l'output simile a questo:

Nota che è in un formato familiare, simile a quello che troverai sul sito Web della documentazione ufficiale di Go.

Godoc usa il commento che precede la dichiarazione del pacchetto come Panoramica. Assicurati che questo commento descriva cosa fa il tuo programma.

Il Indice contiene collegamenti alle dichiarazioni di tipo e ai metodi in modo da potervi navigare rapidamente.

Godoc fornisce anche funzionalità per visualizzare il codice sorgente che compone il pacchetto nel file File di pacchetto sezione.

Migliorare la tua documentazione usando Godoc

Puoi includere più di un semplice testo nella tua documentazione Godoc. Puoi aggiungere URL per i quali Godoc genererà collegamenti e strutturare i tuoi commenti in paragrafi.

Se vuoi collegarti a una risorsa, scrivi l'URL nel tuo commento e Godoc lo riconoscerà e aggiungerà un link. Per i paragrafi, lascia una riga di commento vuota.

// Pacchetto principale
pacchetto principale
// Il documento rappresenta un documento normale.
//
// Collegamento a https://google.com
genere Documento struttura {
 pagine int
 Riferimenti corda
 firmato bollo
}


// Write scrive un nuovo documento nella memoria
//
// Puoi imparare a scrivere da Wikipedia.com
funzScrivere() {
}

Nota che Godoc richiede di scrivere gli URL per intero per poterli collegare. In questo esempio, l'URL di Google include il https:// prefisso, quindi Godoc aggiunge un collegamento ad esso. Poiché il dominio Wikipedia non è un URL completo di per sé, Godoc lo lascerà in pace.

Ecco alcuni dei migliori principi da applicare durante la documentazione del codice Go:

  • Mantieni la tua documentazione semplice e concisa.
  • Inizia la frase di funzioni, tipi e dichiarazioni di variabili con i loro nomi.
  • Inizia una riga con un rientro per preformattarla come codice.
  • I commenti che iniziano con "BUG(name)" come "BUG(joe): Questo non funziona" sono speciali. Godoc li riconoscerà come bug e li segnalerà nella propria sezione della documentazione.

Godoc può alleviare i tuoi problemi di documentazione

Usando Godoc, puoi essere più produttivo e preoccuparti meno dello sforzo di documentare manualmente i tuoi programmi.

Dovresti mantenere la tua documentazione precisa, dettagliata e al punto da rendere più facile la lettura e la comprensione per il tuo pubblico di destinazione. È anche fondamentale mantenere aggiornati i commenti sul codice mentre modifichi il tuo programma.

Consulta la documentazione del pacchetto Godoc per saperne di più sull'utilizzo di Godoc.