¿Qué son las funciones de ejemplo en Go?

Conclusiones clave

• Las funciones de ejemplo en Go son fragmentos de código comprobables que sirven como documentación y pueden usarse para verificar la corrección.
• Las funciones de ejemplo siguen una convención de nomenclatura y se pueden definir para paquetes, funciones, tipos y métodos.
• Las funciones de ejemplo son pruebas ejecutables y se pueden utilizar para garantizar un código confiable y mantener la documentación actualizada.

Uno de los puntos fuertes de Go es su gran cantidad de funciones integradas de prueba y documentación. Entre ellas se encuentra una herramienta muy útil llamada "funciones de ejemplo" que puede ayudarle a verificar su código y explicárselo a otros.

Como desarrollador de Go, debes comprender exactamente qué son las funciones de ejemplo y cómo puedes usarlas para crear software mantenible.

¿Qué son las funciones de ejemplo?

Las funciones de ejemplo (o ejemplos) en Golang son fragmentos de código comprobables que puede agregar a un paquete como documentación y verificar su corrección. Las funciones de ejemplo no toman parámetros y tampoco devuelven un resultado.

Imagina que tienes lo siguiente Multiplicar función en su proyecto:

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

Una función de ejemplo para Multiplicar se verá así:

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

Las funciones de ejemplo utilizan una convención de nomenclatura similar para probar funciones. Defina un ejemplo de función agregando el nombre de la función como sufijo a "Ejemplo", como es el caso con EjemploMultiplicar aquí.

Una mirada más cercana a las funciones de ejemplo

El código de la sección anterior muestra la estructura básica de una función de ejemplo. Lo que constituye un ejemplo es el nombre, el cuerpo de la función y un comentario de salida opcional al final de la función.

Cuando agrega el comentario de salida, Go compila y ejecuta el ejemplo para verificar su corrección, pero sin el comentario, Go solo compila la función de ejemplo, no la ejecuta.

Puede definir un ejemplo para un paquete, una función, un tipo y un método en un tipo.

Definir ejemplos para diferentes entidades requiere enfoques diferentes.

1. Para definir un ejemplo para un paquete, simplemente llame a su función Ejemplo(), sin ningún sufijo. Por ejemplo, aquí hay un ejemplo a nivel de paquete:

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

2. Para definir un ejemplo de una función, simplemente agregue el nombre de la función como sufijo como aprendió anteriormente.

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

3. Para definir un ejemplo para un tipo, agregue el nombre como sufijo a Ejemplo. He aquí un ejemplo:

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

4. Y, por último, para un método de un tipo particular, agrega el nombre del tipo, un guión bajo y luego el nombre del método. Aquí hay una demostración:

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

Puede definir varios ejemplos para una entidad agregando un guión bajo adicional y un sufijo que comience con una letra minúscula. Por ejemplo, EjemploMultiplicar_segundo, EjemploMiEstructura_MiMétodo_segundo.

También puede tener un ejemplo más amplio para explicar la lógica compleja utilizando un ejemplo de archivo completo.

Un ejemplo de archivo completo es un archivo que termina en _prueba.go y contiene exactamente una función de ejemplo, ninguna función de prueba o de referencia, y al menos otra declaración a nivel de paquete. Al mostrar este tipo de ejemplos, godoc mostrará el archivo completo. - El blog de desarrollo de go

El motor Go reconoce y maneja sus funciones de ejemplo de acuerdo con cómo las define.

Puedes usar el Salida desordenada alternativa para comentarios de salida. Esto es particularmente útil en escenarios donde su función devuelve una lista que no se espera en un orden específico.

Documentar su código con funciones de ejemplo

Las funciones de ejemplo son útiles tanto para fines de documentación como de prueba. Una función de ejemplo suele explicar mejor el comportamiento que los comentarios.

Al igual que Javadoc de Java, vamos herramienta de documentación incorporada, godoc, ayuda a documentar el código fácilmente. Pero querrás documentar algunas bibliotecas y funciones juntas para brindar una comprensión más completa de cómo funcionan. Los ejemplos eliminan este inconveniente ya que pueden demostrar las interacciones entre varias unidades de un paquete.

El dios La herramienta asocia automáticamente ejemplos con las funciones, tipos y paquetes a los que pertenecen, según sus especificaciones. También va un paso más allá al permitir la experimentación dentro de la interfaz web de documentación.

Puede probar un paquete o método directamente desde la documentación incluso antes de usarlo en su código.

Esta imagen muestra un ejemplo de la json. Válido funcionar bajo codificación/json:

Uso de funciones de ejemplo para pruebas unitarias

Las funciones de ejemplo de Go también son pruebas ejecutables. Cuando ejecutas el ve a probar comando, el motor ejecuta cada función de ejemplo con un comentario de salida final y garantiza que su salida coincida con lo que hay en el comentario.

Esta capacidad es útil de muchas maneras. Puede servir como una capa extra de pruebas para garantizar un código confiable, también le ayuda a realizar un seguimiento de su documentación a medida que cambia su código.

Por ejemplo, si realiza un cambio que afecta la forma en que se ejecuta una función específica y el resultado que devuelve. Si no actualiza el comentario de salida en el ejemplo para cumplir con los nuevos cambios, las pruebas para ese ejemplo fallarán.

Esto ayuda mucho a evitar la documentación obsoleta, ya que su documentación siempre estará actualizada con el código.

Las funciones de ejemplo producen código y documentación confiables

La documentación es una parte esencial del desarrollo de software, pero pocos lenguajes ofrecen una plataforma tan poderosa para documentar y probar su código.

Go viene con todo lo que necesitas para crear documentación de calidad para tu software, y las funciones de ejemplo son una parte vital de ello. Utilice ejemplos para ayudar a los usuarios y colaboradores a adoptar y comprender su código más rápido.