Que sont les exemples de fonctions dans Go ?

Points clés à retenir

• Les exemples de fonctions dans Go sont des extraits de code testables qui servent de documentation et peuvent être utilisés pour vérifier l'exactitude.
• Les exemples de fonctions suivent une convention de dénomination et peuvent être définies pour des packages, des fonctions, des types et des méthodes.
• Les exemples de fonctions sont des tests exécutables et peuvent être utilisés pour garantir un code fiable et maintenir la documentation à jour.

L’une des forces de Go réside dans sa richesse de fonctionnalités de test et de documentation intégrées. Parmi ceux-ci se trouve un outil très utile appelé « exemples de fonctions » qui peut vous aider à vérifier votre code et à l'expliquer aux autres.

En tant que développeur Go, vous devez comprendre exactement ce que sont des exemples de fonctions et comment vous pouvez les utiliser pour créer un logiciel maintenable.

Que sont les exemples de fonctions?

Des exemples de fonctions (ou d'exemples) dans Golang sont des extraits de code testables que vous pouvez ajouter à un package en tant que documentation et vérifier leur exactitude. Les exemples de fonctions ne prennent pas de paramètres et ne renvoient pas non plus de résultat.

Imaginez que vous ayez ce qui suit Multiplier fonction dans votre projet :

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

Un exemple de fonction pour Multiplier ressemblera à ceci :

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

Les exemples de fonctions utilisent une convention de dénomination similaire pour tester les fonctions. Définissez un exemple de fonction en ajoutant le nom de la fonction comme suffixe à "Exemple", comme c'est le cas avec ExempleMultiplier ici.

Examiner de plus près les exemples de fonctions

Le code de la section précédente montre la structure de base d’un exemple de fonction. Ce qui constitue un exemple est le nom, le corps de la fonction et un commentaire de sortie facultatif à la fin de la fonction.

Lorsque vous ajoutez le commentaire de sortie, Go compile et exécute l'exemple pour vérifier son exactitude, mais sans le commentaire, Go compile uniquement l'exemple de fonction, il ne l'exécute pas.

Vous pouvez définir un exemple pour un package, une fonction, un type et une méthode sur un type.

Définir des exemples pour différentes entités nécessite des approches différentes.

1. Pour définir un exemple de package, appelez simplement votre fonction Exemple(), sans aucun suffixe. Par exemple, voici un exemple au niveau du package :

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

2. Pour définir un exemple de fonction, ajoutez simplement le nom de la fonction comme suffixe, comme vous l'avez appris précédemment.

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

3. Pour définir un exemple pour un type, ajoutez le nom comme suffixe à Exemple. Voici un exemple :

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

4. Et enfin, pour une méthode sur un type particulier, vous ajoutez le nom du type, un trait de soulignement, puis le nom de la méthode. Voici une démonstration :

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

Vous pouvez définir plusieurs exemples pour une entité en ajoutant un trait de soulignement supplémentaire et un suffixe commençant par une lettre minuscule. Par exemple, ExempleMultiply_second, ExempleMyStruct_MyMethod_second.

Vous pouvez également avoir un exemple plus grand pour expliquer une logique complexe en utilisant un exemple de fichier entier.

Un exemple de fichier entier est un fichier qui se termine par _test.go et contient exactement un exemple de fonction, aucune fonction de test ou de référence et au moins une autre déclaration au niveau du package. Lors de l'affichage de tels exemples, godoc affichera l'intégralité du fichier. - Le blog des développeurs

Le moteur Go reconnaît et gère vos exemples de fonctions en fonction de la façon dont vous les définissez.

Vous pouvez utiliser le Sortie non ordonnée alternative pour les commentaires de sortie. Ceci est particulièrement utile dans les scénarios où votre fonction renvoie une liste qui n'est pas attendue dans un ordre spécifique.

Documenter votre code avec des exemples de fonctions

Les exemples de fonctions sont utiles à la fois à des fins de documentation et de test. Un exemple de fonction explique généralement mieux le comportement que les commentaires.

Juste comme Javadoc de Java, Allez outil de documentation intégré, godoc, permet de documenter facilement le code. Mais vous souhaiterez documenter certaines bibliothèques et fonctions ensemble pour donner une compréhension plus complète de leur fonctionnement. Les exemples éliminent ce revers car ils peuvent démontrer les interactions entre les différentes unités d'un package.

Le bondoc L'outil associe automatiquement les exemples aux fonctions, types et packages auxquels ils appartiennent, en fonction de vos spécifications. Il va également plus loin en permettant l'expérimentation au sein de l'interface Web de documentation.

Vous pouvez essayer un package ou une méthode directement à partir de la documentation avant même de l'utiliser dans votre code.

Cette image montre un exemple pour le json. Valide fonction sous encodage/json:

Utilisation d'exemples de fonctions pour les tests unitaires

Les exemples de fonctions Go sont également des tests exécutables. Lorsque vous exécutez le allez tester commande, le moteur exécute chaque exemple de fonction avec un commentaire de sortie final et s'assure que sa sortie correspond à ce qui est dans le commentaire.

Cette fonctionnalité est utile à bien des égards. Il peut servir de couche supplémentaire de tests pour garantir un code fiable, cela vous aide également à garder une trace de votre documentation à mesure que votre code change.

Par exemple, si vous apportez une modification qui a un impact sur la manière dont une fonction spécifique s'exécute et sur le résultat qu'elle renvoie. Si vous ne mettez pas à jour le commentaire de sortie dans l'exemple pour prendre en compte les nouvelles modifications, les tests de cet exemple échoueront.

Cela aide beaucoup à éviter une documentation obsolète, car votre documentation sera toujours à jour avec le code.

Exemples de fonctions produisant un code et une documentation fiables

La documentation est une partie essentielle du développement logiciel, mais peu de langages vous offrent une plateforme aussi puissante pour documenter et tester votre code.

Go est livré avec tout ce dont vous avez besoin pour créer une documentation de qualité pour votre logiciel, et les exemples de fonctions en sont un élément essentiel. Utilisez des exemples pour aider les utilisateurs et les collaborateurs à adopter et à comprendre votre code plus rapidement.