Skill de Documentation de Code

Ce skill fournit des directives complètes pour documenter du code, en privilégiant l'écriture centrée sur l'utilisateur, la clarté et la cohérence.

1. Philosophie générale

• Centré sur l'utilisateur : Écrivez pour la personne qui utilise votre API. Si vous aviez dû chercher comment utiliser quelque chose, documentez-le pour que les autres n'aient pas à le faire.
• Expliquer le "Pourquoi" : Expliquez pourquoi le code existe et comment l'utiliser efficacement, car la signature du code indique déjà ce qu'il fait.
• Soyez concis : Omettez le superflu. Évitez de simplement reformuler le nom du code, car ce n'est pas utile.
• Cohérence : Utilisez une terminologie standard et une mise en forme cohérente.
• APIs publiques : Documentez toutes les APIs publiques (classes, membres, fonctions de haut niveau) sans exception.
• Exemples de code : Envisagez fortement d'ajouter des exemples de code pour expliquer l'utilisation.

2. Structure générale

Suivez cette structure générale pour les commentaires de documentation dans tous les langages :

1. Phrase de résumé : Commencez par un résumé d'une seule phrase sur la première ligne, se terminant par un point.
2. Ligne vide : Suivez le résumé d'une ligne vide.
3. Détails : Ajoutez des paragraphes, des exemples de code ou des listes selon les besoins pour expliquer les paramètres, les valeurs de retour, les exceptions et le comportement.
4. Annotations : Placez les commentaires de doc avant toute annotation de métadonnées.

3. Directives de rédaction

Concision & Style

• Évitez le superflu : Omettez « Cette classe... », « Cette méthode... », « Est utilisée pour... », « Notez que... ».
  • Mauvais : « Cette méthode est utilisée pour calculer le total. »
  • Bon : « Calcule le total. »
• Verbes à la troisième personne : Commencez la documentation des fonctions/méthodes par un verbe singulier à la troisième personne.
  • Exemples : « Retourne... », « Calcule... », « Met à jour... », « Crée... ».
• Groupes nominaux : Commencez la documentation des variables/propriétés par un groupe nominal.
  • Exemples : « La couleur actuelle. », « Une liste des utilisateurs actifs. ».
• Booléens : Commencez toujours par « Indique si » (ou un indicateur clair similaire).
  • Bon : « Indique si ce widget est activé. »
  • Mauvais : « Si ce widget est activé... », « Vrai si... », « Indicateur pour signifier... ».
• Évitez le jargon : Utilisez l'anglais clair sauf si le terme est une norme largement acceptée (p. ex. « HTTP », « URL »).

Mise en forme

• Avec parcimonie : Utilisez les fonctionnalités Markdown (gras, listes) avec parcimonie.
• Pas de HTML : Évitez HTML sauf si strictement nécessaire et supporté par l'outil de documentation.
• Paramètres/Retours/Exceptions : Utilisez la prose pour décrire les paramètres, les valeurs de retour et les exceptions levées. Ne vous fiez pas uniquement à des tags comme @param sauf si imposé par la norme du langage (p. ex. Javadoc).

4. Commentaires d'implémentation

Assurez-vous que les commentaires d'implémentation (//) sont exacts, pertinents, factuels et fournissent des informations qui ne sont pas facilement compréhensibles à partir du code. Supprimez ou reformulez les commentaires qui ne répondent pas à ces critères. Si un commentaire d'implémentation fournit des informations utiles à un utilisateur de l'API qui ne figurent pas déjà dans les commentaires de documentation, déplacez-le vers les commentaires de documentation.

5. Liste de vérification de révision

Utilisez cette liste de vérification pour vérifier votre documentation :

1. [ ] Résumé : Assurez-vous que chaque membre public commence par un résumé d'une phrase se terminant par un point.
2. [ ] Concision : Supprimez le superflu « Cette classe... » ou « Cette fonction... ».
3. [ ] Complétude : Documentez les contraintes strictes (p. ex. « ne doit pas être null ») et les exceptions.
4. [ ] Exemples : Envisagez d'ajouter un exemple de code pour les widgets ou méthodes complexes.

6. Instructions spécifiques au langage

Reportez-vous aux guides de langage pour des instructions détaillées sur la structure, la liaison et les modèles spécifiques au framework :

• Dart / Flutter : references/dart.md
• TypeScript / JavaScript : references/typescript.md
• Python : references/python.md