Hva er eksempelfunksjoner i Go?

Viktige takeaways

• Eksempelfunksjoner i Go er testbare kodebiter som fungerer som dokumentasjon og kan brukes til å verifisere riktigheten.
• Eksempelfunksjoner følger en navnekonvensjon og kan defineres for pakker, funksjoner, typer og metoder.
• Eksempelfunksjoner er kjørbare tester og kan brukes til å sikre pålitelig kode og holde dokumentasjonen oppdatert.

En av Gos styrker er dens vell av innebygde test- og dokumentasjonsfunksjoner. Blant disse er et svært nyttig verktøy kalt "eksempelfunksjoner" som kan hjelpe deg å sjekke koden din og forklare den for andre.

Som Go-utvikler bør du forstå nøyaktig hva eksempelfunksjoner er og hvordan du kan bruke dem til å bygge vedlikeholdbar programvare.

Hva er eksempelfunksjoner?

Eksempelfunksjoner (eller eksempler) i Golang er testbare kodebiter som du kan legge til en pakke som dokumentasjon og verifisere for korrekthet. Eksempelfunksjoner tar ikke parametere og returnerer heller ikke et resultat.

Tenk deg at du har følgende Multiplisere funksjon i prosjektet ditt:

funcMultiply(a, b int)int {
return a * b
}

En eksempelfunksjon for Multiplisere vil se slik ut:

funcExampleMultiply() {
 fmt.Println(Multiply(4, 5))
// Output: 2
}

Eksempelfunksjoner bruker en lignende navnekonvensjon for å teste funksjoner. Definer et funksjonseksempel ved å legge til funksjonens navn som et suffiks til "Eksempel", slik tilfellet er med EksempelMultipliser her.

Ta en nærmere titt på eksempelfunksjoner

Koden i forrige avsnitt viser den grunnleggende strukturen til en eksempelfunksjon. Det som utgjør et eksempel er navnet, funksjonsteksten og en valgfri utdatakommentar på slutten av funksjonen.

Når du legger til utdatakommentaren, kompilerer og kjører Go eksemplet for å bekrefte at det er korrekt, men uten kommentaren kompilerer Go bare eksempelfunksjonen, den kjører den ikke.

Du kan definere et eksempel for en pakke, en funksjon, en type og en metode på en type.

Å definere eksempler for ulike enheter krever ulike tilnærminger.

1. For å definere et eksempel for en pakke, ring bare funksjonen din Eksempel(), uten noe suffiks. For eksempel, her er et eksempel på pakkenivå:

   funcExample() {
    fmt.Println("Hello, world!")
   // Output:
   // Hello, world!
   }

2. For å definere et eksempel for en funksjon, legger du ganske enkelt til funksjonsnavnet som et suffiks som du lærte tidligere.

   funcExampleMultiply() {
    fmt.Println(Multiply(4,5))
   // Output: 2
   }
   

3. For å definere et eksempel for en type, legg til navnet som et suffiks til Eksempel. Her er et eksempel:

   type MyStruct struct {
   // ...
   }
   funcExampleMyStruct() {
   // ...
   }
   

4. Og til slutt, for en metode på en bestemt type, legger du til typenavnet, et understrek og deretter metodenavnet. Her er en demonstrasjon:

   func(m *MyStruct)MyMethod() {
   // ...
   }
   funcExampleMyStruct_MyMethod() {
   // ...
   }
   

Du kan definere flere eksempler for en enhet ved å legge til et ekstra understrek og et suffiks som begynner med en liten bokstav. For eksempel, EksempelMultiply_second, EksempelMyStruct_MyMethod_second.

Du kan også ha et større eksempel for å forklare kompleks logikk ved å bruke en eksempel på hele filen.

Et eksempel på en hel fil er en fil som ender på _test.go og inneholder nøyaktig én eksempelfunksjon, ingen test- eller benchmarkfunksjoner, og minst én annen erklæring på pakkenivå. Når du viser slike eksempler, vil godoc vise hele filen. - Go dev-bloggen

Go-motoren gjenkjenner og håndterer eksempelfunksjonene dine i henhold til hvordan du definerer dem.

Du kan bruke Uordnet utgang alternativ for utdatakommentarer. Dette er spesielt nyttig i scenarier der funksjonen din returnerer en liste som ikke er forventet i en bestemt rekkefølge.

Dokumentere koden din med eksempelfunksjoner

Eksempelfunksjoner er nyttige for både dokumentasjons- og testformål. En eksempelfunksjon gjør vanligvis en bedre jobb med å forklare atferd enn kommentarer gjør.

Akkurat som Javas Javadoc, Go’er innebygd dokumentasjonsverktøy, godoc, hjelper dokumentere kode enkelt. Men du vil dokumentere noen biblioteker og funksjoner sammen for å gi en mer fullstendig forståelse av hvordan de fungerer. Eksempler eliminerer dette tilbakeslaget da de kan demonstrere interaksjonene mellom ulike enheter i en pakke.

De godoc verktøyet knytter eksempler automatisk til funksjonene, typene og pakkene de tilhører, avhengig av dine spesifikasjoner. Det går også ett skritt videre ved å tillate eksperimentering i dokumentasjonsnettgrensesnittet.

Du kan prøve ut en pakke eller metode rett fra dokumentasjonen før du bruker den i koden din.

Dette bildet viser et eksempel for json. Gyldig funksjon under koding/json:

Bruke eksempelfunksjoner for å teste enheten

Go-eksempelfunksjoner er også kjørbare tester. Når du kjører gå test kommandoen kjører motoren hver eksempelfunksjon med en endelig utgangskommentar og sikrer at utgangen samsvarer med det som står i kommentaren.

Denne muligheten er nyttig på mange måter. Den kan tjene som et ekstra lag med testing for å sikre pålitelig kode, hjelper det deg også å holde styr på dokumentasjonen når koden endres.

For eksempel, hvis du gjør en endring som påvirker hvordan en bestemt funksjon kjører og resultatet den returnerer. Hvis du ikke oppdaterer utdatakommentaren i eksemplet for å møte de nye endringene, vil testene for det eksemplet mislykkes.

Dette hjelper mye med å forhindre foreldet dokumentasjon, siden dokumentasjonen din alltid vil være oppdatert med koden.

Eksempelfunksjoner produserer pålitelig kode og dokumentasjon

Dokumentasjon er en viktig del av programvareutvikling, men få språk gir deg en så kraftig plattform for å dokumentere og teste koden din.

Go kommer med alt du trenger for å lage kvalitetsdokumentasjon for programvaren din, og eksempelfunksjoner er en viktig del av det. Bruk eksempler for å hjelpe brukere og samarbeidspartnere å ta i bruk og forstå koden din raskere.