Улучшите свою документацию и тестирование кода за один простой шаг с помощью примеров функций.
Ключевые выводы
- Примеры функций в Go — это тестируемые фрагменты кода, которые служат документацией и могут использоваться для проверки правильности.
- Примеры функций следуют соглашению об именах и могут быть определены для пакетов, функций, типов и методов.
- Примеры функций представляют собой исполняемые тесты и могут использоваться для обеспечения надежности кода и поддержания актуальности документации.
Одной из сильных сторон Go является множество встроенных функций тестирования и документирования. Среди них есть очень полезный инструмент под названием «примеры функций», который поможет вам проверить свой код и объяснить его другим.
Как разработчик Go, вы должны точно понимать, что такое примеры функций и как их можно использовать для создания поддерживаемого программного обеспечения.
Что такое примеры функций?
Примеры функций (или примеров) в Golang — это тестируемые фрагменты кода, которые вы можете добавить в пакет в качестве документации и проверить правильность. Примеры функций не принимают параметры и не возвращают результат.
Представьте, что у вас есть следующее Умножить функция в вашем проекте:
funcMultiply(a, b int)int {
return a * b
}
Пример функции для Умножить будет выглядеть так:
funcExampleMultiply() {
fmt.Println(Multiply(4, 5))
// Output: 2
}
Примеры функций используют аналогичное соглашение об именах для тестирования функций. Определите пример функции, добавив имя функции в качестве суффикса к «Примеру», как в случае с ПримерУмножить здесь.
Более внимательный взгляд на примеры функций
Код в предыдущем разделе показывает базовую структуру примера функции. Пример составляет имя, тело функции и необязательный выводной комментарий в конце функции.
Когда вы добавляете выходной комментарий, Go компилирует и выполняет пример, чтобы проверить его корректность, но без комментария Go только компилирует функцию примера, но не выполняет ее.
Вы можете определить пример пакета, функции, типа и метода типа.
Определение примеров для разных сущностей требует разных подходов.
- Чтобы определить пример пакета, просто вызовите свою функцию Пример(), без какого-либо суффикса. Например, вот пример уровня пакета:
funcExample() {
fmt.Println("Hello, world!")
// Output:
// Hello, world!
} - Чтобы определить пример функции, вы просто добавляете имя функции в качестве суффикса, как вы узнали ранее.
funcExampleMultiply() {
fmt.Println(Multiply(4,5))
// Output: 2
} - Чтобы определить пример типа, добавьте имя в качестве суффикса к Пример. Вот пример:
type MyStruct struct {
// ...
}funcExampleMyStruct() {
// ...
} - И, наконец, для метода определенного типа вы добавляете имя типа, подчеркивание, а затем имя метода. Вот демонстрация:
func(m *MyStruct)MyMethod() {
// ...
}funcExampleMyStruct_MyMethod() {
// ...
}
Вы можете определить несколько примеров для сущности, добавив дополнительное подчеркивание и суффикс, начинающийся со строчной буквы. Например, ПримерMultiply_секунда, ПримерMyStruct_MyMethod_секунду.
Вы также можете использовать более крупный пример для объяснения сложной логики, используя пример всего файла.
Пример целого файла — это файл, который заканчивается на _test.go и содержит ровно одну примерную функцию, никаких тестовых или эталонных функций и как минимум еще одно объявление уровня пакета. При отображении таких примеров godoc покажет весь файл. - Блог разработчиков Go
Движок Go распознает и обрабатывает ваши примеры функций в соответствии с тем, как вы их определяете.
Вы можете использовать Неупорядоченный вывод альтернатива для вывода комментариев. Это особенно полезно в сценариях, где ваша функция возвращает список, который не ожидается в определенном порядке.
Документирование вашего кода с помощью примеров функций
Примеры функций полезны как для документирования, так и для целей тестирования. Функция-пример обычно лучше объясняет поведение, чем комментарии.
Как Javadoc по Java, Го встроенный инструмент документирования godoc, помогает легко документировать код. Но вам захочется документировать некоторые библиотеки и функции вместе, чтобы получить более полное представление о том, как они работают. Примеры устраняют эту проблему, поскольку они могут продемонстрировать взаимодействие между различными частями пакета.
Годок Инструмент автоматически связывает примеры с функциями, типами и пакетами, к которым они принадлежат, в зависимости от ваших спецификаций. Он также делает еще один шаг вперед, позволяя экспериментировать в веб-интерфейсе документации.
Вы можете опробовать пакет или метод прямо из документации, прежде чем использовать его в своем коде.
На этом изображении показан пример json. Действительный функционировать под кодировка/json:
Использование примеров функций для модульного тестирования
Примеры функций Go также являются исполняемыми тестами. Когда вы запускаете иди тестируй Команда, движок запускает каждую примерную функцию с окончательным выходным комментарием и гарантирует, что ее выходные данные соответствуют тому, что находится в комментарии.
Эта возможность полезна во многих отношениях. Он может служить дополнительным слоем тестирование для обеспечения надежности кода, это также поможет вам отслеживать документацию по мере изменения кода.
Например, если вы вносите изменение, которое влияет на выполнение определенной функции и возвращаемый ею результат. Если вы не обновите выходной комментарий в примере, чтобы он соответствовал новым изменениям, тесты для этого примера завершится неудачно.
Это очень помогает предотвратить устаревшую документацию, поскольку ваша документация всегда будет актуальной в соответствии с кодом.
Примеры функций создают надежный код и документацию
Документация — важная часть разработки программного обеспечения, но лишь немногие языки предоставляют такую мощную платформу для документирования и тестирования вашего кода.
Go поставляется со всем необходимым для создания качественной документации для вашего программного обеспечения, и примеры функций являются жизненно важной частью этого. Используйте примеры, чтобы помочь пользователям и сотрудникам быстрее адаптировать и понять ваш код.
