Hvad er eksempelfunktioner i Go?

Nøgle takeaways

• Eksempelfunktioner i Go er testbare kodestykker, der tjener som dokumentation og kan bruges til at verificere rigtigheden.
• Eksempelfunktioner følger en navnekonvention og kan defineres for pakker, funktioner, typer og metoder.
• Eksempelfunktioner er eksekverbare test og kan bruges til at sikre pålidelig kode og holde dokumentationen opdateret.

En af Gos styrker er dens rigdom af indbyggede test- og dokumentationsfunktioner. Blandt disse er et meget nyttigt værktøj kaldet "eksempelfunktioner", som kan hjælpe dig med at tjekke din kode og forklare den for andre.

Som en Go-udvikler bør du forstå præcis, hvad eksempelfunktioner er, og hvordan du kan bruge dem til at bygge vedligeholdelsesvenlig software.

Hvad er eksempelfunktioner?

Eksempelfunktioner (eller eksempler) i Golang er testbare kodestykker, som du kan tilføje til en pakke som dokumentation og verificere for korrekthed. Eksempelfunktioner tager ikke parametre og returnerer heller ikke et resultat.

Forestil dig, at du har følgende Formere sig funktion i dit projekt:

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

En eksempelfunktion til Formere sig vil se sådan ud:

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

Eksempelfunktioner bruger en lignende navngivningskonvention til at teste funktioner. Definer et funktionseksempel ved at tilføje funktionens navn som et suffiks til "Eksempel", som det er tilfældet med Eksempel Multiplicer her.

Se nærmere på eksempler på funktioner

Koden i det foregående afsnit viser den grundlæggende struktur af en eksempelfunktion. Det, der udgør et eksempel, er navnet, funktionsteksten og en valgfri outputkommentar i slutningen af ​​funktionen.

Når du tilføjer outputkommentaren, kompilerer og udfører Go eksemplet for at bekræfte dets korrekthed, men uden kommentaren kompilerer Go kun eksempelfunktionen, den udfører den ikke.

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

At definere eksempler for forskellige enheder kræver forskellige tilgange.

1. For at definere et eksempel for en pakke, ring blot til din funktion Eksempel()uden suffiks. For eksempel, her er et eksempel på pakkeniveau:

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

2. For at definere et eksempel for en funktion, tilføjer du blot funktionsnavnet som et suffiks, som du lærte tidligere.

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

3. For at definere et eksempel for en type skal du tilføje navnet som et suffiks til Eksempel. Her er et eksempel:

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

4. Og til sidst, for en metode på en bestemt type, tilføjer du typenavnet, en understregning og derefter metodenavnet. Her er en demonstration:

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

Du kan definere flere eksempler for en enhed ved at tilføje en ekstra understregning og et suffiks, der begynder med et lille bogstav. For eksempel, EksempelMultiply_second, EksempelMyStruct_MyMethod_second.

Du kan også have et større eksempel til at forklare kompleks logik ved at bruge en eksempel på hele filen.

Et eksempel på en hel fil er en fil, der ender på _test.go og indeholder præcis én eksempelfunktion, ingen test- eller benchmarkfunktioner og mindst én anden erklæring på pakkeniveau. Når sådanne eksempler vises, vil godoc vise hele filen. - Go dev-bloggen

Go-motoren genkender og håndterer dine eksempelfunktioner i henhold til, hvordan du definerer dem.

Du kan bruge Uordnet output alternativ til outputkommentarer. Dette er især nyttigt i scenarier, hvor din funktion returnerer en liste, der ikke forventes i en bestemt rækkefølge.

Dokumentation af din kode med eksempelfunktioner

Eksempelfunktioner er nyttige til både dokumentations- og testformål. En eksempelfunktion gør normalt et bedre stykke arbejde med at forklare adfærd, end kommentarer gør.

Ligesom Javas Javadoc, Go’er indbygget dokumentationsværktøj, godoc, hjælper med at dokumentere kode nemt. Men du vil gerne dokumentere nogle biblioteker og funktioner sammen for at give en mere fuldstændig forståelse af, hvordan de fungerer. Eksempler eliminerer dette tilbageslag, da de kan demonstrere interaktionerne mellem forskellige enheder i en pakke.

Det godoc værktøjet forbinder automatisk eksempler med de funktioner, typer og pakker, de tilhører, afhængigt af dine specifikationer. Det går også et skridt videre ved at tillade eksperimenter inden for dokumentationswebgrænsefladen.

Du kan prøve en pakke eller metode direkte fra dokumentationen, før du overhovedet bruger den i din kode.

Dette billede viser et eksempel på json. Gyldig funktion under kodning/json:

Brug af eksempelfunktioner til enhedstest

Go-eksempelfunktioner er også eksekverbare tests. Når du kører gå til test kommando, kører motoren hver eksempelfunktion med en endelig outputkommentar og sikrer, at dens output matcher det, der er i kommentaren.

Denne evne er nyttig på mange måder. Den kan fungere som et ekstra lag af test for at sikre pålidelig kode, det hjælper dig også med at holde styr på din dokumentation, efterhånden som din kode ændres.

For eksempel, hvis du foretager en ændring, der påvirker, hvordan en specifik funktion kører, og resultatet, den returnerer. Hvis du ikke opdaterer outputkommentaren i eksemplet for at opfylde de nye ændringer, vil testene for det eksempel mislykkes.

Dette hjælper en hel del med at forhindre forældet dokumentation, da din dokumentation altid vil være opdateret med koden.

Eksempelfunktioner Frembringer pålidelig kode og dokumentation

Dokumentation er en væsentlig del af softwareudvikling, men få sprog giver dig så kraftfuld en platform til at dokumentere og teste din kode.

Go kommer med alt, hvad du behøver for at skabe kvalitetsdokumentation til din software, og eksempelfunktioner er en vigtig del af det. Brug eksempler til at hjælpe brugere og samarbejdspartnere med at adoptere og forstå din kode hurtigere.