Commentaires de code : bonnes pratiques et conventions#
Les commentaires en Go commencent par le symbole // pour une seule ligne, ou peuvent être encadrés par /* */ pour plusieurs lignes.
Il est recommandé de commencer chaque commentaire par le nom de l'élément qu'il documente.
Les commentaires de code doivent être clairs, concis et pertinents. Ils doivent expliquer le "pourquoi" et non le "comment". Le code lui-même montre comment il fonctionne.
Évitez les commentaires redondants ou inutiles qui n'apportent pas d'information supplémentaire.
La documentation d'une fonction ou d'une méthode doit commencer par le nom de la fonction ou de la méthode.
Lors de l'écriture de commentaires, il faut être conscient que le code peut être lu et utilisé par des personnes dans le monde entier. Il est donc important d'éviter les références culturelles ou locales spécifiques qui pourraient ne pas être comprises par tout le monde.
Utilisation de "godoc" pour générer la documentation#
godoc est l'outil officiel de documentation pour le langage Go.
godoc extrait les commentaires du code source pour générer une documentation en HTML ou en texte brut.
Pour générer la documentation locale, utilisez la commande godoc -http=:6060 dans le terminal. Vous pouvez ensuite accéder à la documentation à l'adresse http://localhost:6060.
godoc génère automatiquement une page d'index pour tous les packages documentés.
Pour consulter la documentation d'un package spécifique, utilisez la commande godoc package/subpackage.
Documentation des packages, fonctions, types et méthodes#
Chaque package doit avoir un commentaire de package juste avant la déclaration package. Ce commentaire donne une description générale du package.
Chaque fonction, type et méthode publique doit avoir un commentaire expliquant son but, son utilisation et, si nécessaire, son comportement en cas d'erreurs.
Les noms de fonctions, de types et de méthodes doivent être en CamelCase et commencer par une majuscule pour être exportés et visibles en dehors du package.
Les commentaires pour les méthodes doivent être placés directement au-dessus de la méthode et commencer par le nom de la méthode.
Intégration de la documentation dans un workflow de développement#
La documentation doit être considérée comme une partie essentielle du code et doit être maintenue à jour tout au long du cycle de vie du développement.
La revue de code doit également inclure la revue des commentaires et de la documentation.
L'outil golint peut être utilisé pour vérifier la qualité des commentaires. golint peut être installé avec go get -u golang.org/x/lint/golint et utilisé avec la commande golint ./... dans le répertoire du projet.
Pour un workflow automatisé, intégrez golint ou godoc dans votre processus de CI/CD pour vérifier la qualité de la documentation à chaque commit.
Les erreurs ou les avertissements de documentation doivent être traités avec le même sérieux que les erreurs de compilation.