Migliora la documentazione e il test del codice in un semplice passaggio con funzioni di esempio.
Punti chiave
- Le funzioni di esempio in Go sono frammenti di codice testabili che servono come documentazione e possono essere utilizzati per verificare la correttezza.
- Le funzioni di esempio seguono una convenzione di denominazione e possono essere definite per pacchetti, funzioni, tipi e metodi.
- Le funzioni di esempio sono test eseguibili e possono essere utilizzate per garantire un codice affidabile e mantenere aggiornata la documentazione.
Uno dei punti di forza di Go è la sua ricchezza di funzionalità di test e documentazione integrate. Tra questi c'è uno strumento molto utile chiamato "funzioni di esempio" che può aiutarti a controllare il tuo codice e spiegarlo ad altri.
In qualità di sviluppatore Go, dovresti capire esattamente quali sono le funzioni di esempio e come utilizzarle per creare software gestibile.
Cosa sono le funzioni di esempio?
Le funzioni di esempio (o esempi) in Golang sono frammenti di codice testabili che puoi aggiungere a un pacchetto come documentazione e verificarne la correttezza. Le funzioni di esempio non accettano parametri e non restituiscono nemmeno un risultato.
Immagina di avere quanto segue Moltiplicare funzione nel tuo progetto:
funcMultiply(a, b int)int {
return a * b
}
Una funzione di esempio per Moltiplicare sarà simile a questo:
funcExampleMultiply() {
fmt.Println(Multiply(4, 5))
// Output: 2
}
Le funzioni di esempio utilizzano una convenzione di denominazione simile per testare le funzioni. Definire un esempio di funzione aggiungendo il nome della funzione come suffisso a "Esempio", come nel caso di EsempioMoltiplicare Qui.
Uno sguardo più da vicino alle funzioni di esempio
Il codice nella sezione precedente mostra la struttura di base di una funzione di esempio. Ciò che costituisce un esempio è il nome, il corpo della funzione e un commento di output opzionale alla fine della funzione.
Quando aggiungi il commento di output, Go compila ed esegue l'esempio per verificarne la correttezza, ma senza il commento Go compila solo la funzione di esempio, non la esegue.
È possibile definire un esempio per un pacchetto, una funzione, un tipo e un metodo su un tipo.
La definizione di esempi per entità diverse richiede approcci diversi.
- Per definire un esempio per un pacchetto, chiama semplicemente la tua funzione Esempio(), senza alcun suffisso. Ad esempio, ecco un esempio a livello di pacchetto:
funcExample() {
fmt.Println("Hello, world!")
// Output:
// Hello, world!
} - Per definire un esempio per una funzione, aggiungi semplicemente il nome della funzione come suffisso come hai imparato in precedenza.
funcExampleMultiply() {
fmt.Println(Multiply(4,5))
// Output: 2
} - Per definire un esempio per un tipo, aggiungere il nome come suffisso a Esempio. Ecco un esempio:
type MyStruct struct {
// ...
}funcExampleMyStruct() {
// ...
} - Infine, per un metodo su un tipo particolare, aggiungi il nome del tipo, un carattere di sottolineatura e quindi il nome del metodo. Ecco una dimostrazione:
func(m *MyStruct)MyMethod() {
// ...
}funcExampleMyStruct_MyMethod() {
// ...
}
Puoi definire più esempi per un'entità aggiungendo un carattere di sottolineatura aggiuntivo e un suffisso che inizia con una lettera minuscola. Per esempio, EsempioMoltiplica_secondo, EsempioMyStruct_MyMethod_second.
Puoi anche avere un esempio più ampio per spiegare la logica complessa utilizzando a intero file esempio.
Un esempio di file intero è un file che termina con _test.go e contiene esattamente una funzione di esempio, nessuna funzione di test o benchmark e almeno un'altra dichiarazione a livello di pacchetto. Quando si visualizzano tali esempi, Godoc mostrerà l'intero file. - Il blog degli sviluppatori Go
Il motore Go riconosce e gestisce le funzioni di esempio in base a come le definisci.
Puoi usare il Uscita non ordinata alternativa per i commenti di output. Ciò è particolarmente utile negli scenari in cui la tua funzione restituisce un elenco non previsto in un ordine specifico.
Documentare il codice con funzioni di esempio
Le funzioni di esempio sono utili sia a scopo di documentazione che di test. Una funzione di esempio di solito spiega meglio il comportamento rispetto ai commenti.
Proprio come Javadoc di Java, Vai strumento di documentazione integrato, godoc, aiuta a documentare facilmente il codice. Ma ti consigliamo di documentare insieme alcune librerie e funzioni per fornire una comprensione più completa di come funzionano. Gli esempi eliminano questo ostacolo poiché possono dimostrare le interazioni tra le varie unità di un pacchetto.
IL godoc Lo strumento associa automaticamente gli esempi alle funzioni, ai tipi e ai pacchetti a cui appartengono, a seconda delle tue specifiche. Inoltre fa un ulteriore passo avanti consentendo la sperimentazione all'interno dell'interfaccia web della documentazione.
Puoi provare un pacchetto o un metodo direttamente dalla documentazione prima ancora di utilizzarlo nel tuo codice.
Questa immagine mostra un esempio per il json. Valido funzione sotto codifica/json:
Utilizzo delle funzioni di esempio per il test unitario
Anche le funzioni di esempio Go sono test eseguibili. Quando esegui il file vai a provare comando, il motore esegue ogni funzione di esempio con un commento di output finale e garantisce che il suo output corrisponda a quanto contenuto nel commento.
Questa funzionalità è utile in molti modi. Può servire come strato aggiuntivo di test per garantire un codice affidabile, ti aiuta anche a tenere traccia della documentazione man mano che il codice cambia.
Ad esempio, se apporti una modifica che influisce sul modo in cui viene eseguita una funzione specifica e sul risultato restituito. Se non aggiorni il commento di output nell'esempio per soddisfare le nuove modifiche, i test per quell'esempio falliranno.
Ciò aiuta molto a prevenire la documentazione obsoleta, poiché la documentazione sarà sempre aggiornata con il codice.
Funzioni di esempio producono codice e documentazione affidabili
La documentazione è una parte essenziale dello sviluppo del software, ma pochi linguaggi offrono una piattaforma così potente per documentare e testare il codice.
Go viene fornito con tutto il necessario per creare documentazione di qualità per il tuo software e le funzioni di esempio ne sono una parte vitale. Utilizza esempi per aiutare utenti e collaboratori ad adottare e comprendere il tuo codice più velocemente.
