Co jsou ukázkové funkce v Go?

Klíčové věci

• Ukázkové funkce v Go jsou testovatelné úryvky kódu, které slouží jako dokumentace a lze je použít k ověření správnosti.
• Vzorové funkce se řídí konvencí pojmenování a lze je definovat pro balíčky, funkce, typy a metody.
• Ukázkové funkce jsou spustitelné testy a lze je použít k zajištění spolehlivého kódu a udržování dokumentace v aktuálním stavu.

Jednou ze silných stránek Go je velké množství vestavěných testovacích a dokumentačních funkcí. Mezi nimi je velmi užitečný nástroj zvaný „příkladové funkce“, který vám může pomoci zkontrolovat váš kód a vysvětlit jej ostatním.

Jako vývojář Go byste měli přesně rozumět tomu, co jsou ukázkové funkce a jak je můžete použít k vytvoření udržovatelného softwaru.

Co jsou příklady funkcí?

Ukázkové funkce (nebo příklady) v Golangu jsou testovatelné úryvky kódu, které můžete přidat do balíčku jako dokumentaci a ověřit jejich správnost. Ukázkové funkce neberou parametry a ani nevrací výsledek.

Představte si, že máte následující Násobit funkce ve vašem projektu:

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

Příklad funkce pro Násobit bude vypadat takto:

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

Příkladové funkce používají k testování funkcí podobnou konvenci pojmenování. Definujte příklad funkce přidáním názvu funkce jako přípony k „Příklad“, jako je tomu v případě Příklad Vynásobte tady.

Bližší pohled na ukázkové funkce

Kód v předchozí části ukazuje základní strukturu ukázkové funkce. Příklad tvoří název, tělo funkce a volitelný výstupní komentář na konci funkce.

Když přidáte výstupní komentář, Go zkompiluje a spustí příklad, aby ověřil jeho správnost, ale bez komentáře Go pouze zkompiluje ukázkovou funkci, nespustí ji.

U typu můžete definovat příklad pro balíček, funkci, typ a metodu.

Definování příkladů pro různé entity vyžaduje různé přístupy.

1. Chcete-li definovat příklad pro balíček, stačí zavolat svou funkci Příklad(), bez jakékoli přípony. Zde je například příklad na úrovni balíčku:

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

2. Chcete-li definovat příklad funkce, jednoduše přidejte název funkce jako příponu, jak jste se naučili dříve.

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

3. Chcete-li definovat příklad pro typ, přidejte název jako příponu k Příklad. Zde je příklad:

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

4. A nakonec pro metodu na konkrétním typu přidáte název typu, podtržítko a poté název metody. Zde je ukázka:

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

Pro entitu můžete definovat více příkladů přidáním dalšího podtržítka a přípony začínající malým písmenem. Například, PříkladVynásobte_sekundu, ExampleMyStruct_MyMethod_second.

Můžete mít také větší příklad pro vysvětlení složité logiky pomocí a příklad celého souboru.

Příkladem celého souboru je soubor, který končí na _test.go a obsahuje přesně jednu ukázkovou funkci, žádné testovací nebo benchmarkové funkce a alespoň jednu další deklaraci na úrovni balíčku. Při zobrazení takových příkladů godoc zobrazí celý soubor. - Blog go dev

Modul Go rozpoznává a zpracovává vaše ukázkové funkce podle toho, jak je definujete.

Můžete použít Neuspořádaný výstup alternativa pro výstupní komentáře. To je užitečné zejména ve scénářích, kdy vaše funkce vrací seznam, který není očekáván v určitém pořadí.

Dokumentování kódu pomocí příkladů funkcí

Ukázkové funkce jsou užitečné pro účely dokumentace i testování. Příkladová funkce obvykle lépe vysvětluje chování než komentáře.

Stejně jako Javadoc Java, Jdi vestavěný dokumentační nástroj, godoc, usnadňuje kód dokumentu. Ale budete chtít zdokumentovat některé knihovny a funkce společně, abyste lépe pochopili, jak fungují. Příklady eliminují tuto překážku, protože mohou demonstrovat interakce mezi různými jednotkami balíčku.

The godoc nástroj automaticky spojuje příklady s funkcemi, typy a balíčky, ke kterým patří, v závislosti na vašich specifikacích. Jde také o krok dále tím, že umožňuje experimentování ve webovém rozhraní dokumentace.

Balíček nebo metodu si můžete vyzkoušet přímo z dokumentace ještě předtím, než je použijete ve svém kódu.

Tento obrázek ukazuje příklad pro json. Platný funkce pod kódování/json:

Použití vzorových funkcí k testování jednotek

Příklady funkcí Go jsou také spustitelné testy. Když spustíte jít testovat engin spustí každou ukázkovou funkci s konečným výstupním komentářem a zajistí, aby jeho výstup odpovídal tomu, co je v komentáři.

Tato schopnost je užitečná v mnoha ohledech. Může sloužit jako další vrstva testování pro zajištění spolehlivého kódu, také vám pomůže sledovat vaši dokumentaci při změnách kódu.

Pokud například provedete změnu, která ovlivní běh konkrétní funkce a výsledek, který vrátí. Pokud neaktualizujete výstupní komentář v příkladu, aby vyhovoval novým změnám, testy pro tento příklad selžou.

To velmi pomáhá při prevenci zastaralé dokumentace, protože vaše dokumentace bude vždy aktuální s kódem.

Příklad funkcí vytváří spolehlivý kód a dokumentaci

Dokumentace je nezbytnou součástí vývoje softwaru, ale jen málo jazyků vám poskytne tak výkonnou platformu pro dokumentaci a testování kódu.

Go přichází se vším, co potřebujete k vytvoření kvalitní dokumentace pro váš software, a ukázkové funkce jsou toho nezbytnou součástí. Použijte příklady, které uživatelům a spolupracovníkům pomohou rychleji přijmout a pochopit váš kód.