Verbeter uw documentatie en codetest in één eenvoudige stap met voorbeeldfuncties.
Belangrijkste leerpunten
- Voorbeeldfuncties in Go zijn testbare codefragmenten die dienen als documentatie en kunnen worden gebruikt om de juistheid te verifiëren.
- Voorbeeldfuncties volgen een naamgevingsconventie en kunnen worden gedefinieerd voor pakketten, functies, typen en methoden.
- Voorbeeldfuncties zijn uitvoerbare tests en kunnen worden gebruikt om betrouwbare code te garanderen en documentatie up-to-date te houden.
Een van de sterke punten van Go is de rijkdom aan ingebouwde test- en documentatiefuncties. Hiertoe behoort een zeer nuttig hulpmiddel genaamd "voorbeeldfuncties" waarmee u uw code kunt controleren en aan anderen kunt uitleggen.
Als Go-ontwikkelaar moet u precies begrijpen wat voorbeeldfuncties zijn en hoe u deze kunt gebruiken om onderhoudbare software te bouwen.
Wat zijn voorbeeldfuncties?
Voorbeeldfuncties (of voorbeelden) in Golang zijn testbare codefragmenten die u als documentatie aan een pakket kunt toevoegen en op juistheid kunt verifiëren. Voorbeeldfuncties nemen geen parameters en retourneren ook geen resultaat.
Stel je voor dat je het volgende hebt Vermenigvuldigen functie in uw project:
funcMultiply(a, b int)int {
return a * b
}
Een voorbeeldfunctie voor Vermenigvuldigen zal er als volgt uitzien:
funcExampleMultiply() {
fmt.Println(Multiply(4, 5))
// Output: 2
}
Voorbeeldfuncties gebruiken een vergelijkbare naamgevingsconventie om functies te testen. Definieer een functievoorbeeld door de naam van de functie als achtervoegsel toe te voegen aan "Voorbeeld", zoals het geval is met VoorbeeldVermenigvuldigen hier.
Voorbeeldfuncties nader bekijken
De code in de vorige sectie toont de basisstructuur van een voorbeeldfunctie. Wat een voorbeeld vormt, is de naam, de functietekst en een optioneel uitvoercommentaar aan het einde van de functie.
Wanneer u de uitvoeropmerking toevoegt, compileert Go het voorbeeld en voert het uit om de juistheid ervan te verifiëren, maar zonder de opmerking compileert Go alleen de voorbeeldfunctie, maar voert deze niet uit.
U kunt een voorbeeld definiëren voor een pakket, een functie, een type en een methode voor een type.
Het definiëren van voorbeelden voor verschillende entiteiten vereist verschillende benaderingen.
- Om een voorbeeld voor een pakket te definiëren, roept u gewoon uw functie op Voorbeeld(), zonder enig achtervoegsel. Hier is bijvoorbeeld een voorbeeld op pakketniveau:
funcExample() {
fmt.Println("Hello, world!")
// Output:
// Hello, world!
} - Om een voorbeeld voor een functie te definiëren, voegt u eenvoudigweg de functienaam als achtervoegsel toe, zoals u eerder hebt geleerd.
funcExampleMultiply() {
fmt.Println(Multiply(4,5))
// Output: 2
} - Als u een voorbeeld voor een type wilt definiëren, voegt u de naam toe als achtervoegsel Voorbeeld. Hier is een voorbeeld:
type MyStruct struct {
// ...
}funcExampleMyStruct() {
// ...
} - En ten slotte voegt u voor een methode van een bepaald type de typenaam, een onderstrepingsteken en vervolgens de methodenaam toe. Hier is een demonstratie:
func(m *MyStruct)MyMethod() {
// ...
}funcExampleMyStruct_MyMethod() {
// ...
}
U kunt meerdere voorbeelden voor een entiteit definiëren door een extra onderstrepingsteken en een achtervoegsel toe te voegen dat begint met een kleine letter. Bijvoorbeeld, VoorbeeldMultiply_second, VoorbeeldMijnStruct_MijnMethode_seconde.
U kunt ook een groter voorbeeld hebben om complexe logica uit te leggen door a te gebruiken voorbeeld van een heel bestand.
Een voorbeeld van een heel bestand is een bestand dat eindigt op _test.go en bevat precies één voorbeeldfunctie, geen test- of benchmarkfuncties, en ten minste één andere declaratie op pakketniveau. Bij het weergeven van dergelijke voorbeelden zal godoc het gehele bestand tonen. - Het go dev-blog
De Go-engine herkent en verwerkt uw voorbeeldfuncties op basis van hoe u ze definieert.
U kunt gebruik maken van de Ongeordende uitvoer alternatief voor uitvoercommentaar. Dit is met name handig in scenario's waarin uw functie een lijst retourneert die niet in een specifieke volgorde wordt verwacht.
Documenteer uw code met voorbeeldfuncties
Voorbeeldfuncties zijn nuttig voor zowel documentatie- als testdoeleinden. Een voorbeeldfunctie kan gedrag doorgaans beter verklaren dan opmerkingen.
Net als Java's Javadoc, Go's ingebouwde documentatietool, godoc, helpt bij het eenvoudig documenteren van code. Maar u wilt een aantal bibliotheken en functies samen documenteren om een vollediger inzicht te krijgen in hoe ze werken. Voorbeelden elimineren deze tegenslag omdat ze de interacties tussen verschillende eenheden van een pakket kunnen demonstreren.
De goed tool koppelt voorbeelden automatisch aan de functies, typen en pakketten waartoe ze behoren, afhankelijk van uw specificaties. Het gaat nog een stap verder door experimenten binnen de documentatiewebinterface mogelijk te maken.
U kunt een pakket of methode rechtstreeks vanuit de documentatie uitproberen voordat u het zelfs maar in uw code gebruikt.
Deze afbeelding toont een voorbeeld voor de json. Geldig functie onder codering/json:
Voorbeeldfuncties gebruiken voor het testen van eenheden
Go-voorbeeldfuncties zijn ook uitvoerbare tests. Wanneer u de ga testen commando voert de engine elke voorbeeldfunctie uit met een laatste uitvoercommentaar en zorgt ervoor dat de uitvoer overeenkomt met wat er in het commentaar staat.
Deze mogelijkheid is op veel manieren nuttig. Het kan dienen als een extra laag testen om betrouwbare code te garanderen, helpt het u ook uw documentatie bij te houden terwijl uw code verandert.
Als u bijvoorbeeld een wijziging aanbrengt die van invloed is op de manier waarop een specifieke functie wordt uitgevoerd en op het resultaat dat deze retourneert. Als u de uitvoeropmerking in het voorbeeld niet bijwerkt om aan de nieuwe wijzigingen te voldoen, zullen de tests voor dat voorbeeld mislukken.
Dit helpt enorm bij het voorkomen van verouderde documentatie, omdat uw documentatie altijd up-to-date zal zijn met de code.
Voorbeeldfuncties Produceer betrouwbare code en documentatie
Documentatie is een essentieel onderdeel van softwareontwikkeling, maar weinig talen bieden u zo'n krachtig platform om uw code te documenteren en te testen.
Go wordt geleverd met alles wat u nodig heeft om kwaliteitsdocumentatie voor uw software te maken, en voorbeeldfuncties zijn daar een essentieel onderdeel van. Gebruik voorbeelden zodat gebruikers en medewerkers uw code sneller kunnen overnemen en begrijpen.
