Melhore sua documentação e teste de código em uma etapa fácil com funções de exemplo.
Principais conclusões
- Funções de exemplo em Go são trechos de código testáveis que servem como documentação e podem ser usados para verificar a correção.
- Funções de exemplo seguem uma convenção de nomenclatura e podem ser definidas para pacotes, funções, tipos e métodos.
- Funções de exemplo são testes executáveis e podem ser usadas para garantir código confiável e manter a documentação atualizada.
Um dos pontos fortes do Go é a riqueza de recursos integrados de teste e documentação. Entre elas está uma ferramenta altamente útil chamada “funções de exemplo” que pode ajudá-lo a verificar seu código e explicá-lo a outras pessoas.
Como desenvolvedor Go, você deve entender exatamente o que são funções de exemplo e como usá-las para criar software sustentável.
O que são funções de exemplo?
Funções de exemplo (ou exemplos) em Golang são trechos de código testáveis que você pode adicionar a um pacote como documentação e verificar a correção. Funções de exemplo não aceitam parâmetros e também não retornam resultado.
Imagine que você tem o seguinte Multiplicar função em seu projeto:
funcMultiply(a, b int)int {
return a * b
}
Um exemplo de função para Multiplicar ficará assim:
funcExampleMultiply() {
fmt.Println(Multiply(4, 5))
// Output: 2
}
Funções de exemplo usam uma convenção de nomenclatura semelhante para testar funções. Defina um exemplo de função adicionando o nome da função como sufixo a "Exemplo", como é o caso de Exemplo Multiplicar aqui.
Analisando mais de perto funções de exemplo
O código da seção anterior mostra a estrutura básica de uma função de exemplo. O que constitui um exemplo é o nome, o corpo da função e um comentário de saída opcional no final da função.
Quando você adiciona o comentário de saída, Go compila e executa o exemplo para verificar sua correção, mas sem o comentário, Go apenas compila a função de exemplo, não a executa.
Você pode definir um exemplo para um pacote, uma função, um tipo e um método em um tipo.
Definir exemplos para diferentes entidades requer abordagens diferentes.
- Para definir um exemplo de pacote, basta chamar sua função Exemplo(), sem nenhum sufixo. Por exemplo, aqui está um exemplo em nível de pacote:
funcExample() {
fmt.Println("Hello, world!")
// Output:
// Hello, world!
} - Para definir um exemplo de função, basta adicionar o nome da função como sufixo, conforme aprendido anteriormente.
funcExampleMultiply() {
fmt.Println(Multiply(4,5))
// Output: 2
} - Para definir um exemplo para um tipo, adicione o nome como sufixo a Exemplo. Aqui está um exemplo:
type MyStruct struct {
// ...
}funcExampleMyStruct() {
// ...
} - E por último, para um método de um tipo específico, você adiciona o nome do tipo, um sublinhado e, em seguida, o nome do método. Aqui está uma demonstração:
func(m *MyStruct)MyMethod() {
// ...
}funcExampleMyStruct_MyMethod() {
// ...
}
Você pode definir vários exemplos para uma entidade adicionando um sublinhado extra e um sufixo começando com uma letra minúscula. Por exemplo, ExemploMultiply_second, ExemploMyStruct_MyMethod_second.
Você também pode ter um exemplo maior para explicar lógica complexa usando um exemplo de arquivo inteiro.
Um exemplo de arquivo inteiro é um arquivo que termina em _teste.go e contém exatamente uma função de exemplo, nenhuma função de teste ou benchmark e pelo menos uma outra declaração em nível de pacote. Ao exibir tais exemplos, o godoc mostrará o arquivo inteiro. - O blog go dev
O mecanismo Go reconhece e trata suas funções de exemplo de acordo com como você as define.
Você pode usar o Saída não ordenada alternativa para comentários de saída. Isto é particularmente útil em cenários onde a sua função retorna uma lista que não é esperada em uma ordem específica.
Documentando seu código com funções de exemplo
Funções de exemplo são úteis para fins de documentação e teste. Uma função de exemplo geralmente explica melhor o comportamento do que os comentários.
Assim como Javadoc de Java, Vai ferramenta de documentação integrada, godoc, ajuda a documentar o código facilmente. Mas você desejará documentar algumas bibliotecas e funções juntas para fornecer uma compreensão mais completa de como elas funcionam. Os exemplos eliminam esse revés, pois podem demonstrar as interações entre as diversas unidades de uma embalagem.
O Deus A ferramenta associa automaticamente exemplos às funções, tipos e pacotes aos quais pertencem, dependendo de suas especificações. Ele também vai um passo além, permitindo a experimentação na interface web da documentação.
Você pode experimentar um pacote ou método diretamente da documentação antes mesmo de usá-lo em seu código.
Esta imagem mostra um exemplo para o json. Válido função sob codificação/json:
Usando funções de exemplo para teste de unidade
As funções de exemplo Go também são testes executáveis. Quando você executa o vá testar comando, o mecanismo executa cada função de exemplo com um comentário de saída final e garante que sua saída corresponda ao que está no comentário.
Esse recurso é útil de várias maneiras. Pode servir como uma camada extra de testes para garantir código confiável, também ajuda você a acompanhar sua documentação à medida que seu código muda.
Por exemplo, se você fizer uma alteração que afete o modo como uma função específica é executada e o resultado que ela retorna. Se você não atualizar o comentário de saída no exemplo para atender às novas alterações, os testes desse exemplo falharão.
Isso ajuda muito a evitar documentação obsoleta, pois sua documentação estará sempre atualizada com o código.
Funções de exemplo produzem código e documentação confiáveis
A documentação é uma parte essencial do desenvolvimento de software, mas poucas linguagens oferecem uma plataforma tão poderosa para documentar e testar seu código.
Go vem com tudo que você precisa para criar documentação de qualidade para seu software, e funções de exemplo são uma parte vital disso. Use exemplos para ajudar usuários e colaboradores a adotar e compreender seu código com mais rapidez.