Javítsa a dokumentációt és a kódtesztet egyetlen egyszerű lépésben példafunkciókkal.
Kulcs elvitelek
- A Go példafunkciói tesztelhető kódrészletek, amelyek dokumentációként szolgálnak, és felhasználhatók a helyesség ellenőrzésére.
- A példafüggvények elnevezési konvenciót követnek, és definiálhatók csomagokhoz, függvényekhez, típusokhoz és metódusokhoz.
- A példafüggvények végrehajtható tesztek, és megbízható kód biztosítására és a dokumentáció naprakészen tartására használhatók.
A Go egyik erőssége a rengeteg beépített tesztelési és dokumentációs funkció. Ezek között található egy rendkívül hasznos eszköz, az úgynevezett „példafüggvények”, amelyek segítségével ellenőrizheti kódját, és elmagyarázhatja azt másoknak.
Go fejlesztőként pontosan meg kell értenie, mik azok a példafunkciók, és hogyan használhatja őket karbantartható szoftverek létrehozásához.
Mik azok a példafüggvények?
A Golang példafüggvényei (vagy példái) tesztelhető kódrészletek, amelyeket dokumentációként hozzáadhat egy csomaghoz, és ellenőrizheti a helyességét. A példafüggvények nem vesznek fel paramétereket és nem adnak vissza eredményt sem.
Képzeld el, hogy a következővel rendelkezel Szorozni funkció a projektben:
funcMultiply(a, b int)int {
return a * b
}
Példafüggvény ehhez Szorozni így fog kinézni:
funcExampleMultiply() {
fmt.Println(Multiply(4, 5))
// Output: 2
}
A példafüggvények hasonló elnevezési konvenciót használnak a függvények tesztelésére. Határozzon meg egy függvénypéldát úgy, hogy a függvény nevét a "Példa" utótagjaként adja hozzá, ahogy az a PéldaSzorzás itt.
A példafüggvények közelebbi pillantása
Az előző részben található kód egy példafüggvény alapvető felépítését mutatja be. Példaként a név, a függvény törzse és egy opcionális kimeneti megjegyzés található a függvény végén.
Amikor hozzáadja a kimeneti megjegyzést, a Go lefordítja és végrehajtja a példát, hogy ellenőrizze annak helyességét, de megjegyzés nélkül a Go csak a példafüggvényt fordítja le, nem hajtja végre.
Megadhat egy példát egy csomagra, egy függvényre, egy típusra és egy típuson egy metódusra.
A különböző entitásokhoz tartozó példák meghatározása eltérő megközelítést igényel.
- Egy csomag példájának meghatározásához egyszerűen hívja meg a függvényt Példa(), utótag nélkül. Például itt van egy csomagszintű példa:
funcExample() {
fmt.Println("Hello, world!")
// Output:
// Hello, world!
} - Ha egy függvényre példát szeretne definiálni, egyszerűen adja hozzá a függvény nevét utótagként, ahogy azt korábban megtanulta.
funcExampleMultiply() {
fmt.Println(Multiply(4,5))
// Output: 2
} - Ha egy típusra példát szeretne megadni, adja hozzá a nevet a következőhöz utótagként Példa. Íme egy példa:
type MyStruct struct {
// ...
}funcExampleMyStruct() {
// ...
} - Végül pedig egy adott típushoz tartozó metódushoz hozzá kell adni a típusnevet, aláhúzást, majd a metódus nevét. Íme egy bemutató:
func(m *MyStruct)MyMethod() {
// ...
}funcExampleMyStruct_MyMethod() {
// ...
}
Egy entitáshoz több példát is megadhat egy extra aláhúzás és egy kisbetűvel kezdődő utótag hozzáadásával. Például, PéldaSzorzás_másodperc, PéldaMyStruct_MyMethod_second.
Egy nagyobb példát is készíthet az összetett logika magyarázatára az a használatával teljes fájl példa.
A teljes fájlra példa egy fájl, amely a következőre végződik _test.go és pontosan egy példafüggvényt tartalmaz, nincs teszt vagy benchmark függvény, és legalább egy másik csomagszintű deklaráció. Ilyen példák megjelenítésekor a godoc a teljes fájlt megjeleníti. - A go dev blog
A Go motor felismeri és kezeli az Ön példafüggvényeit aszerint, hogy Ön hogyan határozza meg azokat.
Használhatja a Rendeletlen kimenet alternatíva a kimeneti megjegyzésekhez. Ez különösen hasznos olyan esetekben, amikor a függvény olyan listát ad vissza, amely nem egy meghatározott sorrendben várható.
A kód dokumentálása példafunkciókkal
A példafüggvények dokumentálási és tesztelési célokra egyaránt hasznosak. Egy példafüggvény általában jobban magyarázza a viselkedést, mint a megjegyzések.
Akárcsak Java Javadoc, Go's beépített dokumentációs eszköz, godoc, segít könnyen dokumentálni a kódot. De érdemes együtt dokumentálnia néhány könyvtárat és funkciót, hogy teljesebb képet kapjon működésükről. A példák kiküszöbölik ezt a visszaesést, mivel bemutathatják a csomag különböző egységei közötti kölcsönhatásokat.
A goddoc Az eszköz automatikusan társítja a példákat azokhoz a függvényekhez, típusokhoz és csomagokhoz, amelyekhez tartoznak, az Ön specifikációitól függően. Egy lépéssel tovább megy azáltal, hogy lehetővé teszi a kísérletezést a dokumentációs webes felületen belül.
Kipróbálhat egy csomagot vagy módszert közvetlenül a dokumentációból, mielőtt még felhasználná a kódjában.
Ez a kép példát mutat a json. Érvényes alatti funkciót kódolás/json:
Példafüggvények használata az egységteszthez
A Go példafüggvények is végrehajtható tesztek. Amikor futtatja a menj tesztelni parancsot, a motor minden példafüggvényt lefuttat egy végső kimeneti megjegyzéssel, és biztosítja, hogy a kimenet megfeleljen a megjegyzésben szereplőnek.
Ez a képesség sok szempontból hasznos. Extra rétegként szolgálhat tesztelés a megbízható kód biztosítása érdekében, segít nyomon követni a dokumentációt, ahogy a kód változik.
Például, ha olyan módosítást hajt végre, amely befolyásolja egy adott függvény futását és az általa visszaadott eredményt. Ha nem frissíti a kimeneti megjegyzést a példában, hogy megfeleljen az új módosításoknak, akkor a példa tesztje sikertelen lesz.
Ez nagyban segít megelőzni az elavult dokumentációt, mivel a dokumentáció mindig naprakész lesz a kóddal.
A példafunkciók megbízható kódot és dokumentációt készítenek
A dokumentáció a szoftverfejlesztés elengedhetetlen része, de kevés nyelv kínál ilyen hatékony platformot a kód dokumentálására és tesztelésére.
A Go mindent tartalmaz, amire szüksége van a szoftver minőségi dokumentációjának elkészítéséhez, és a példafunkciók ennek létfontosságú részét képezik. Használjon példákat, hogy segítsen a felhasználóknak és az együttműködőknek gyorsabban elfogadni és megérteni a kódot.
