Какво представляват примерните функции в Go?

Ключови изводи

• Примерните функции в Go са тествани кодови фрагменти, които служат като документация и могат да се използват за проверка на коректността.
• Примерните функции следват конвенция за именуване и могат да бъдат дефинирани за пакети, функции, типове и методи.
• Примерните функции са изпълними тестове и могат да се използват за осигуряване на надежден код и поддържане на документацията актуална.

Една от силните страни на Go е изобилието от вградени функции за тестване и документиране. Сред тях е много полезен инструмент, наречен "примерни функции", който може да ви помогне да проверите кода си и да го обясните на другите.

Като разработчик на Go трябва да разберете какво точно представляват примерните функции и как можете да ги използвате за изграждане на поддържаем софтуер.

Какво представляват примерните функции?

Примерни функции (или примери) в Golang са тестови фрагменти от код, които можете да добавите към пакет като документация и да проверите за коректност. Примерните функции не приемат параметри и не връщат резултат.

Представете си, че имате следното Умножете функция във вашия проект:

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

Примерна функция за Умножете ще изглежда така:

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

Примерните функции използват подобна конвенция за именуване за тестване на функции. Дефинирайте пример за функция, като добавите името на функцията като суфикс към „Пример“, както е в случая с Примерно умножение тук.

Разглеждане по-отблизо на примерни функции

Кодът в предишния раздел показва основната структура на примерна функция. Това, което съставлява пример, е името, тялото на функцията и незадължителен изходен коментар в края на функцията.

Когато добавите изходния коментар, Go компилира и изпълнява примера, за да провери коректността му, но без коментара Go само компилира примерната функция, не я изпълнява.

Можете да дефинирате пример за пакет, функция, тип и метод за тип.

Дефинирането на примери за различни обекти изисква различни подходи.

1. За да дефинирате пример за пакет, просто извикайте вашата функция Пример(), без никакъв суфикс. Например, ето пример на ниво пакет:

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

2. За да дефинирате пример за функция, просто добавяте името на функцията като суфикс, както научихте по-рано.

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

3. За да дефинирате пример за тип, добавете името като суфикс към Пример. Ето един пример:

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

4. И накрая, за метод на определен тип добавяте името на типа, долна черта и след това името на метода. Ето една демонстрация:

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

Можете да дефинирате множество примери за обект, като добавите допълнително долна черта и суфикс, започващ с малка буква. Например, ПримерУмножение_секунда, ExampleMyStruct_MyMethod_second.

Можете също така да имате по-голям пример, за да обясните сложна логика, като използвате a пример за цял файл.

Пример за цял файл е файл, който завършва на _test.go и съдържа точно една примерна функция, без тестови или сравнителни функции и поне една друга декларация на ниво пакет. При показване на такива примери godoc ще покаже целия файл. - Блогът на go dev

Механизмът Go разпознава и обработва вашите примерни функции според това как ги дефинирате.

Можете да използвате Неподреден изход алтернатива за изходни коментари. Това е особено полезно в сценарии, при които вашата функция връща списък, който не се очаква в определен ред.

Документиране на вашия код с примерни функции

Примерните функции са полезни както за целите на документирането, така и за тестването. Една примерна функция обикновено върши по-добра работа за обяснение на поведението, отколкото коментарите.

Точно като Javadoc на Java, Go's вграден инструмент за документиране, godoc, помага за лесното документиране на кода. Но ще искате да документирате някои библиотеки и функции заедно, за да дадете по-пълно разбиране за това как работят. Примерите елиминират тази пречка, тъй като могат да демонстрират взаимодействията между различни единици на пакет.

The godoc инструментът автоматично свързва примери с функциите, типовете и пакетите, към които принадлежат, в зависимост от вашите спецификации. Той също така отива една крачка напред, като позволява експериментиране в рамките на уеб интерфейса на документацията.

Можете да изпробвате пакет или метод направо от документацията, преди дори да го използвате във вашия код.

Това изображение показва пример за json. Валиден функция под кодиране/json:

Използване на примерни функции за модулен тест

Примерните функции на Go също са изпълними тестове. Когато стартирате иди на тест машината изпълнява всяка примерна функция с окончателен изходен коментар и гарантира, че нейният изход съвпада с това, което е в коментара.

Тази способност е полезна по много начини. Може да служи като допълнителен слой на тестване, за да се гарантира надежден код, също така ви помага да следите документацията си, когато кодът ви се променя.

Например, ако направите промяна, която влияе върху начина на изпълнение на конкретна функция и резултата, който връща. Ако не актуализирате изходния коментар в примера, за да отговаря на новите промени, тестовете за този пример ще се провалят.

Това помага много за предотвратяване на остаряла документация, тъй като документацията ви винаги ще бъде актуална с кода.

Примерни функции създават надежден код и документация

Документацията е съществена част от разработката на софтуер, но малко езици ви дават толкова мощна платформа за документиране и тестване на вашия код.

Go идва с всичко необходимо за създаване на качествена документация за вашия софтуер, а примерните функции са жизненоважна част от това. Използвайте примери, за да помогнете на потребителите и сътрудниците да приемат и разберат кода ви по-бързо.