Förbättra din dokumentation och kodtest i ett enkelt steg med exempelfunktioner.
Viktiga takeaways
- Exempelfunktioner i Go är testbara kodsnuttar som fungerar som dokumentation och kan användas för att verifiera korrektheten.
- Exempelfunktioner följer en namnkonvention och kan definieras för paket, funktioner, typer och metoder.
- Exempelfunktioner är körbara tester och kan användas för att säkerställa tillförlitlig kod och hålla dokumentationen uppdaterad.
En av Gos styrkor är dess rikedom av inbyggda test- och dokumentationsfunktioner. Bland dessa finns ett mycket användbart verktyg som kallas "exempelfunktioner" som kan hjälpa dig att kontrollera din kod och förklara den för andra.
Som Go-utvecklare bör du förstå exakt vad exempelfunktioner är och hur du kan använda dem för att bygga underhållbar programvara.
Vad är exempelfunktioner?
Exempelfunktioner (eller exempel) i Golang är testbara kodavsnitt som du kan lägga till i ett paket som dokumentation och verifiera att de är korrekta. Exempelfunktioner tar inte parametrar och returnerar inte heller ett resultat.
Föreställ dig att du har följande Multiplicera funktion i ditt projekt:
funcMultiply(a, b int)int {
return a * b
}
En exempelfunktion för Multiplicera kommer se ut så här:
funcExampleMultiply() {
fmt.Println(Multiply(4, 5))
// Output: 2
}
Exempelfunktioner använder en liknande namnkonvention för att testa funktioner. Definiera ett funktionsexempel genom att lägga till funktionens namn som ett suffix till "Exempel", som är fallet med ExempelMultiplicera här.
Ta en närmare titt på exempelfunktioner
Koden i föregående avsnitt visar den grundläggande strukturen för en exempelfunktion. Det som utgör ett exempel är namnet, funktionskroppen och en valfri utdatakommentar i slutet av funktionen.
När du lägger till utdatakommentaren kompilerar och kör Go exemplet för att verifiera dess korrekthet, men utan kommentaren kompilerar Go bara exempelfunktionen, den körs inte.
Du kan definiera ett exempel för ett paket, en funktion, en typ och en metod för en typ.
Att definiera exempel för olika enheter kräver olika tillvägagångssätt.
- För att definiera ett exempel för ett paket, ring bara din funktion Exempel(), utan något suffix. Till exempel, här är ett exempel på paketnivå:
funcExample() {
fmt.Println("Hello, world!")
// Output:
// Hello, world!
} - För att definiera ett exempel för en funktion lägger du helt enkelt till funktionsnamnet som ett suffix som du lärde dig tidigare.
funcExampleMultiply() {
fmt.Println(Multiply(4,5))
// Output: 2
} - För att definiera ett exempel för en typ, lägg till namnet som ett suffix till Exempel. Här är ett exempel:
type MyStruct struct {
// ...
}funcExampleMyStruct() {
// ...
} - Och slutligen, för en metod på en viss typ, lägger du till typnamnet, ett understreck och sedan metodnamnet. Här är en demonstration:
func(m *MyStruct)MyMethod() {
// ...
}funcExampleMyStruct_MyMethod() {
// ...
}
Du kan definiera flera exempel för en enhet genom att lägga till ett extra understreck och ett suffix som börjar med en liten bokstav. Till exempel, ExempelMultiply_second, ExempelMyStruct_MyMethod_second.
Du kan också ha ett större exempel för att förklara komplex logik genom att använda en exempel på hela filen.
Ett helt filexempel är en fil som slutar på _test.go och innehåller exakt en exempelfunktion, inga test- eller benchmarkfunktioner och minst en annan deklaration på paketnivå. När du visar sådana exempel kommer godoc att visa hela filen. - Go dev-bloggen
Go-motorn känner igen och hanterar dina exempelfunktioner enligt hur du definierar dem.
Du kan använda Oordnad utmatning alternativ för output kommentarer. Detta är särskilt användbart i scenarier där din funktion returnerar en lista som inte förväntas i en specifik ordning.
Dokumentera din kod med exempelfunktioner
Exempelfunktioner är användbara för både dokumentations- och teständamål. En exempelfunktion gör vanligtvis ett bättre jobb med att förklara beteende än vad kommentarer gör.
Precis som Javas Javadoc, Gå s inbyggt dokumentationsverktyg, godoc, hjälper till att dokumentera kod enkelt. Men du vill dokumentera några bibliotek och funktioner tillsammans för att ge en mer fullständig förståelse för hur de fungerar. Exempel eliminerar detta bakslag eftersom de kan demonstrera interaktionerna mellan olika enheter i ett paket.
De godoc verktyget associerar automatiskt exempel med de funktioner, typer och paket de tillhör, beroende på dina specifikationer. Det går också ett steg längre genom att tillåta experiment i dokumentationens webbgränssnitt.
Du kan prova ett paket eller en metod direkt från dokumentationen innan du ens använder det i din kod.
Den här bilden visar ett exempel för json. Giltig funktion under kodning/json:
Använda exempelfunktioner för att testa enheten
Go-exempelfunktioner är också körbara tester. När du kör gå testa kommandot kör motorn varje exempelfunktion med en slutlig utmatningskommentar och säkerställer att dess utdata matchar det som finns i kommentaren.
Denna förmåga är användbar på många sätt. Den kan fungera som ett extra lager av testning för att säkerställa tillförlitlig kod, det hjälper dig också att hålla reda på din dokumentation när din kod ändras.
Till exempel, om du gör en ändring som påverkar hur en specifik funktion körs och resultatet den returnerar. Om du inte uppdaterar utdatakommentaren i exemplet för att möta de nya ändringarna kommer testerna för det exemplet att misslyckas.
Detta hjälper en hel del för att förhindra inaktuell dokumentation, eftersom din dokumentation alltid kommer att vara uppdaterad med koden.
Exempelfunktioner producera pålitlig kod och dokumentation
Dokumentation är en viktig del av mjukvaruutveckling, men få språk ger dig en så kraftfull plattform för att dokumentera och testa din kod.
Go kommer med allt du behöver för att skapa kvalitetsdokumentation för din programvara, och exempelfunktioner är en viktig del av det. Använd exempel för att hjälpa användare och medarbetare att anta och förstå din kod snabbare.
