Que sont les fonctions d’exemple en Go ?

Principaux enseignements

  • Les fonctions d’exemple en Go sont des bouts de code testables qui servent de documentation et peuvent être utilisés pour vérifier la correction.
  • Les fonctions d’exemple suivent une convention de dénomination et peuvent être définies pour les packages, les fonctions, les types et les méthodes.
  • Les fonctions d’exemple sont des tests exécutables et peuvent être utilisées pour garantir un code fiable et maintenir la documentation à jour.

L’un des points forts de Go est sa richesse en fonctionnalités intégrées de test et de documentation. Parmi celles-ci, un outil très utile appelé « fonctions d’exemple » peut vous aider à vérifier votre code et à l’expliquer à d’autres personnes.

En tant que développeur Go, vous devez comprendre exactement ce que sont les fonctions d’exemple et comment vous pouvez les utiliser pour construire un logiciel maintenable.

Que sont les fonctions d’exemple ?

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

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

Un exemple de fonction pour Multiplier se présente comme suit :

Les fonctions d’exemple utilisent une convention de dénomination similaire à celle des fonctions de test. Définissez un exemple de fonction en ajoutant le nom de la fonction en suffixe à « Exemple », comme c’est le cas avec ExempleMultiplier ici.

Regarder de plus près les exemples de fonctions

Le code de la section précédente montre la structure de base d’une fonction d’exemple. Un exemple se compose du nom, du corps de la fonction et d’un commentaire de sortie facultatif à la fin de la fonction.

Voir aussi :  Comment créer un tableau Markdown

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 seulement la fonction exemple, 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.

La définition d’exemples pour différentes entités nécessite des approches différentes.

  1. Pour définir un exemple pour un package, il suffit d’appeler votre fonction Exemple() sans suffixe. Par exemple, voici un exemple au niveau du paquetage :
  2. Pour définir un exemple pour une fonction, il suffit d’ajouter le nom de la fonction comme suffixe, comme vous l’avez appris précédemment.
  3. Pour définir un exemple pour un type, il suffit d’ajouter le nom du type en tant que suffixe à Exemple. Voici un exemple :
  4. Enfin, pour une méthode sur un type particulier, on ajoute le nom du type, un trait de soulignement, puis le nom de la méthode. Voici une démonstration :

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. Voici un exemple, ExempleMultiplier_seconde, ExempleMyStruct_MyMethod_second.

Vous pouvez également utiliser un exemple plus large pour expliquer une logique complexe en utilisant un fichier d’un fichier entier.

Un exemple de fichier entier est un fichier qui se termine par _test.go et qui contient exactement une fonction d’exemple, aucune fonction de test ou de référence, et au moins une autre déclaration au niveau du paquet. Lors de l’affichage de tels exemples, godoc affichera le fichier entier. – Le blog de go dev

Le moteur Go reconnaît et traite vos exemples de fonctions selon la manière dont vous les avez définis.

Voir aussi :  Guide du débutant pour la création et la gestion des limaces de Django

Vous pouvez utiliser la fonction Sortie non ordonnée pour les commentaires de sortie. Ceci est particulièrement utile dans les cas 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 fonctions d’exemple sont utiles à la fois pour la documentation et pour les tests. Une fonction d’exemple explique généralement mieux le comportement que les commentaires.

Tout comme Javadoc de Java, l’outil de documentation intégré de Go, godoc, permet de documenter facilement le code. Mais vous voudrez documenter certaines bibliothèques et fonctions ensemble pour donner une compréhension plus complète de leur fonctionnement. Les exemples éliminent cet inconvénient car ils peuvent démontrer les interactions entre les différentes unités d’un paquetage.

Les godoc associe automatiquement les exemples aux fonctions, types et paquets auxquels ils appartiennent, en fonction de vos spécifications. Il va également plus loin en permettant l’expérimentation dans l’interface web de la documentation.

Vous pouvez tester 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 paquetage json.Valid sous la fonction encodage/json:

Utilisation de fonctions d’exemple pour les tests unitaires

Les fonctions d’exemple Go sont également des tests exécutables. Lorsque vous exécutez la fonction go test le moteur exécute chaque fonction d’exemple avec un commentaire de sortie final et s’assure que sa sortie correspond à ce qui est indiqué dans le commentaire.

Voir aussi :  Un guide pour télécharger des images avec une application Django

Cette capacité est utile à bien des égards. Elle peut servir de couche supplémentaire de test pour garantir un code fiable, elle vous aide également à garder une trace de votre documentation au fur et à mesure que votre code évolue.

Par exemple, si vous apportez une modification qui a un impact sur l’exécution d’une fonction spécifique et sur le résultat qu’elle renvoie. Si vous ne mettez pas à jour le commentaire de sortie dans l’exemple pour répondre aux nouveaux changements, les tests pour cet exemple échoueront.

Cela permet d’éviter une documentation périmée, car votre documentation sera toujours à jour par rapport au code.

Les fonctions d’exemple produisent un code et une documentation fiables

La documentation est un élément essentiel du développement de logiciels, mais peu de langages 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 fonctions d’exemple sont une partie vitale de cela. Utilisez des exemples pour aider les utilisateurs et les collaborateurs à adopter et à comprendre votre code plus rapidement.

Cliquez pour évaluer cet article !
[Total: Moyenne : ]

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *