Documentation en Go : écrire du code qui parle de lui-même

Pourquoi la documentation en Go est un super-pouvoir, et non une corvée ennuyeuse

Imaginez : vous ouvrez un projet Go écrit par quelqu'un d'autre, et il n'y a aucun commentaire. Les fonctions s'appellent f1, f2, et les structures Data et MoreData. Cela vous dit quelque chose ? Si oui, vous savez à quelle vitesse l'enthousiasme peut laisser place à l'envie de fermer le dépôt.

Go est un langage qui adore la simplicité et la clarté. Mais même le code le plus propre ne parle pas toujours de lui-même. Une bonne documentation en Go n'est pas simplement un « geste aimable » pour vos collègues. C'est un outil professionnel qui :

\n
• Accélère l'intégration des nouveaux développeurs ;
\n
• Aide à éviter les bogues (vous vous souvenez que les commentaires peuvent éviter une mauvaise utilisation de l'API ?) ;
\n
• Génère automatiquement de belles pages sur pkg.go.dev ;
\n
• Améliore la qualité du code (essayez d'écrire un commentaire pour une mauvaise fonction – vous aurez vous-même envie de la réécrire).
\n

Dans cet article, nous allons passer en revue les meilleures pratiques pour documenter les projets Go. Des règles de base de godoc aux exemples concrets que vous pourrez appliquer dès aujourd'hui. C'est parti !

La philosophie de la documentation en Go : moins de mots, plus de sens

Go n'est ni Java ni Python. Ici, personne n'écrit de Javadoc de plusieurs pages ou des docstrings de 20 lignes. La philosophie de Go est simple : documentez le comportement, pas l'implémentation.

Dans le guide officiel Effective Go, il est clairement dit : les commentaires doivent décrire ce que fait le code, pas comment il le fait. Si votre code est si complexe qu'il nécessite une explication de l'algorithme, il est peut-être temps de le simplifier.

Les principes de base :

\n
• Un commentaire est une phrase. Commencez par le nom de la fonction ou du type. // Calculate returns the result of the calculation. – parfait. // This function calculates... – on perd le focus.
\n
• Écrivez en anglais. Go est un langage international, et la documentation en anglais est la norme de facto. Mais si votre projet est strictement destiné à une équipe francophone, vous pouvez aussi l'écrire en français. L'important est la cohérence.
\n
• N'expliquez pas l'évidence. // SetName sets the name – inutile. Préférez : // SetName updates the user's display name. Must be called before Save.
\n

Godoc : votre meilleur ami et documentaliste automatique

Go est livré avec un outil intégré appelé godoc. Il analyse les commentaires directement dans le code et génère une documentation HTML. Cela signifie que votre documentation vit à côté du code – et se met à jour en même temps.

Comment ça marche ? Très simplement. Écrivez un commentaire juste avant une entité exportée (fonction, type, structure, constante) – et godoc le récupérera.

Exemple d'un package de base :

// Package calculator provides basic arithmetic operations.\npackage calculator\n\n// Add returns the sum of two integers.\nfunc Add(a, b int) int {\n    return a + b\n}\n\n// Subtract returns the difference of two integers.\nfunc Subtract(a, b int) int {\n    return a - b\n}

Maintenant, lancez godoc -http :8080 et ouvrez votre navigateur. Vous verrez une belle page avec la description du package et de chaque fonction. Magique !

Les bonnes pratiques pour godoc

\n
• Commentez toujours le package. Le commentaire du package est la première chose que l'utilisateur voit. Il doit décrire l'objectif du package et, idéalement, contenir un exemple d'utilisation.
\n
• N'oubliez pas les types et les structures. Si une structure a des champs qui ne sont pas évidents d'après leur nom, documentez-les aussi.
\n
• Utilisez une ligne vide. godoc considère le premier paragraphe comme une description courte, et tout le reste comme des détails. Séparez-les par une ligne vide.
\n

// User repre