reyalka/astro

Écrire des commentaires

Objectif

Les commentaires de ce dépôt sont lus par des contributeurs, des mois ou des années après leur rédaction, sans aucun du contexte dont vous disposez actuellement. Cette compétence définit qui est ce lecteur, à quoi sert chaque type de commentaire et quels motifs sont interdits.

Périmètre

Cette compétence régit les commentaires destinés aux contributeurs dans le code source TypeScript/JavaScript. Elle ne s'applique pas à la documentation utilisateur finale :

• Les blocs JSDoc marqués @docs dans packages/astro/src/types/public/config.ts et packages/astro/src/core/errors/errors-data.ts sont extraits par un outil externe docgen et publiés sur le site de documentation d'Astro. Suivez packages/astro/src/core/errors/README.md pour ceux-ci, et obtenez une relecture de l'équipe docs — la CI regénère la référence lorsque types/public/** change.
• Les autres JSDoc dans types/public/** sont exposés aux utilisateurs via l'IntelliSense de l'éditeur. Rédigez-les pour les utilisateurs d'Astro construisant un site, pas pour les contributeurs lisant le code source.

Tout ce qui suit concerne le code source qu'un contributeur lit à HEAD.

Le lecteur

Écrivez pour un contributeur Astro compétent en TypeScript mais qui n'a accès à aucun de votre contexte actuel : ni cette conversation, ni la pull request, ni le ticket, ni le diff. Il ne voit que le dépôt à HEAD.

Deux conséquences en découlent directement :

1. Ne racontez jamais l'historique des modifications. Des mots comme « maintenant », « auparavant », « ne...plus », « la nouvelle approche » n'ont aucun sens à HEAD, où une seule approche existe. Décrivez comment le code fonctionne, pas comment il en est arrivé là. (Une mention @deprecated fait exception — voir Conventions — car elle décrit le futur du contrat, dont le lecteur a besoin.)
2. Ne vous adressez jamais au relecteur. Un commentaire qui justifie votre modification (« ceci gère correctement X ») appartient à la description de la PR, pas au code source. Le commentaire doit justifier le code tel qu'il est, en permanence.

Trois types de commentaires, trois rôles différents

Type	Syntaxe	Rôle	Contenu
Vue d'ensemble de fichier/module	/** */ en haut du fichier	Explication	Pourquoi le module existe, les concepts et termes qu'il définit, comment les parties s'articulent, justification de conception
Documentation d'élément	/** */ directement au-dessus d'une déclaration	Référence	Le contrat : comportement, paramètres, valeur de retour, erreurs levées, invariants. Neutre et factuel
Commentaires inline	// à l'intérieur d'un corps	Justification	Uniquement ce que le code ne peut pas dire : contraintes, contournements (avec liens vers les tickets), couplage non évident

Ne mélangez pas les rôles. Les détails d'implémentation n'ont pas leur place dans le contrat /** */ — mettez-les dans des commentaires // à l'intérieur du corps. Le contrat n'a pas sa place éparpillé dans des commentaires inline — mettez-le sur la déclaration.

Documentation du comportement

Lorsqu'une documentation d'élément est justifiée, rédigez le contrat pour un lecteur humain, pas comme une traduction de l'implémentation. Cela n'exige pas de JSDoc pour chaque fonction ; les noms, types et structure devraient porter seuls le comportement évident.

• Commencez par une description en langage clair de ce que la fonction retourne ou accomplit.
• Utilisez des phrases courtes ou de longueur moyenne avec une idée principale chacune.
• Évitez le jargon interne d'Astro lorsque les appelants n'en ont pas besoin. Si un terme technique est nécessaire, expliquez-le dans le même paragraphe.
• Décrivez les mises en garde visibles par l'appelant qui peuvent être surprenantes : comportement de repli, limites de travail, résultats ambigus, ordre de surcharge, effets de bord, et les conditions qui retournent undefined, null, un résultat vide ou une autre valeur indéterminée.
• Documentez les erreurs levées lorsque les appelants sont censés les distinguer ou s'en remettre.
• Ne décrivez pas les détails d'implémentation sauf si les appelants en ont besoin pour comprendre le comportement ou utiliser l'API en toute sécurité.

Ajoutez un exemple lorsque le comportement dépend d'une relation que la signature ne peut pas montrer clairement. Les cas courants dans Astro et TypeScript incluent :

• quelle surcharge est sélectionnée ;
• comment les arguments sont mappés aux paramètres optionnels ou rest ;
• quel point d'entrée public d'Astro expose un symbole implémenté ou ré-exporté ailleurs ;
• comportement de repli pour les routes ambiguës, la configuration incomplète ou le contenu manquant ;
• un résultat dont le sens n'est pas évident d'après son type.

Introduisez l'exemple en prose avant le bloc de code. Indiquez ce qu'il démontre et quel résultat est attendu. Gardez les extraits minimaux, autonomes et rédigés du point de vue d'un utilisateur Astro ou de l'appelant interne propriétaire du contrat.

La documentation d'un module doit décrire un concept durable, une frontière architecturale ou une raison de conception. Ne listez pas les exportations individuelles simplement pour résumer le fichier ; ces inventaires deviennent obsolètes à mesure que les symboles sont ajoutés ou renommés. Si un module n'a aucun concept durable à expliquer, utilisez une brève description d'une ligne ou aucune vue d'ensemble.

Le test de suppression

Avant d'écrire un commentaire, demandez-vous : est-ce que cela énonce quelque chose que le lecteur ne peut pas retrouver à partir du code lui-même ?

• Si l'information est déjà portée par les noms, types ou structure, n'écrivez pas le commentaire. Si le nom ne la porte pas, améliorez le nom.
• Informations qui légitimement nécessitent un commentaire : un invariant, une justification, un couplage avec du code ailleurs, un contournement avec un lien, un comportement surprenant d'une dépendance, un terme spécialisé que le module définit.

Lors de l'édition ultérieure, le même test s'applique en sens inverse : un commentaire qui ne le réussit plus doit être supprimé, pas laissé pourrir.

Liez le ticket pour les contournements

Cette base de code ancre systématiquement les contournements à une source. Tout commentaire qui explique un contournement, un HACK, un garde-fou de régression ou un comportement surprenant d'une dépendance doit lier le ticket GitHub ou la PR qui le motive. Le lien est ce qui permet à un futur lecteur de savoir si le contournement est toujours nécessaire.

// Gère les nanostores recommandés. Seul @nanostores/preact est requis d'après nos tests !
// Explication complète et rapport de bug associé : https://github.com/withastro/astro/pull/3667
'@nanostores/preact',

Un contournement sans lien est impossible à distinguer d'une erreur.

Motifs interdits

Narrer la ligne suivante. Supprimez-les à vue :

// Incrémente le compteur de génération
generation += 1;

Narration de l'historique des modifications. Réécrivez comme une justification au présent :

// MAUVAIS : Nous résolvons maintenant lightningcss depuis la racine de l'utilisateur au lieu de la nôtre.
// BON : lightningcss est une dépendance optionnelle de pair, donc elle se résout depuis la racine du projet utilisateur.

Justification adressée au relecteur. Déplacez l'argument dans la PR :

// MAUVAIS : Ceci gère correctement le chemin multi-encodé du rapport de bug.
// BON : Un chemin toujours encodé après MAX_DECODE_ITERATIONS est rejeté, donc
//       le middleware et le routage ne peuvent jamais diverger sur le chemin décodé.

JSDoc redondant. Un bloc /** */ qui reformule le nom de la déclaration ne dit rien :

// MAUVAIS :
/** Compile les styles. */
function compileStyles(...)

// BON :
/** Réécrit les références `url()` relatives dans `css` par rapport à `base`, en laissant
 *  les URL absolues et les données intactes. */
function compileStyles(...)

Formulations vagues. « Certains cas », « diverses raisons », « gère les cas limites », « etc. » — soit nommez-les, soit supprimez la phrase.

Émojis. Interdits dans le code source, y compris les commentaires (politique à l'échelle du dépôt).

Bandeaux de section ad-hoc (// ----- helpers -----, // ==== TYPES ====). Ce dépôt n'a pas de convention de pliage // #region ; n'ajoutez pas de bandeaux. Si un fichier est assez long pour que vous soyez tenté d'en utiliser un, c'est un signal pour diviser le fichier, pas pour le décorer.

Conventions dans ce dépôt

Balises JSDoc. @param nom - description, @returns et @throws énoncent le contrat. Mettez un type entre accolades (@returns {Promise<string>}) uniquement lorsque la signature seule est ambiguë. Utilisez @example avec un bloc ```js pour une utilisation non évidente.

Références croisées. Utilisez {@link Symbole} / {@linkcode Symbole} plutôt qu'un nom nu, afin qu'un renommage mette à jour la référence et que les éditeurs puissent sauter à la cible.

@internal. Marque une API qui ne fait pas partie de la surface publique. C'est une convention uniquement — il n'y a ni typedoc ni api-extractor ici pour la supprimer — donc elle documente l'intention mais ne remplace pas les modificateurs d'accès.

@deprecated. Indiquez la migration, puis l'horizon de suppression :

/** @deprecated Utilisez la méthode d'instance `cookies.consume()` à la place. Ceci sera supprimé dans Astro 7 */

Dites quoi utiliser à la place, pas seulement que le symbole est déprécié. Cette note au futur est une information contractuelle dont le lecteur a besoin, pas une narration interdite de l'historique des modifications.

TODO. Utilisez // TODO: pour un travail différé ; liez un ticket lorsqu'il en existe un. Pour un travail conditionné à une fenêtre de rupture, utilisez l'idiome établi // TODO: remove in Astro <N>. Il n'y a pas de FIXME dans ce dépôt — ne l'introduisez pas.

Modification de code existant

• Préservez les commentaires existants. Si votre modification altère le comportement, étendez ou corrigez le texte spécifique — ne le remplacez jamais par du texte générique. Supprimer un contexte durement acquis est pire que de laisser un commentaire légèrement obsolète.
• Lorsque votre modification rend un commentaire faux, corrigez-le dans le même diff. Un commentaire obsolète est pire qu'aucun commentaire.
• Adaptez-vous à la densité environnante. Un module fortement documenté mérite le même niveau sur les nouveaux éléments ; ne couvrez pas un module peu documenté de commentaires de façon systématique.

Auto-vérification avant de terminer

Après avoir terminé toute tâche qui a touché des commentaires, relisez uniquement les commentaires de votre diff, isolés des modifications de code :

1. Chacun réussit-il le test de suppression ?
2. L'un d'eux fait-il référence à la conversation, à la modification elle-même ou au relecteur ?
3. Chaque contournement lie-t-il son ticket ou sa PR ?
4. Un lecteur sans accès au diff comprendrait-il chacun d'eux ?

Corrigez ou supprimez ce qui échoue. La suppression est le comportement par défaut ; un commentaire manquant coûte moins cher qu'un commentaire trompeur.

Références

• Diátaxis — le framework derrière la répartition explication / référence / justification ci-dessus.
• packages/astro/src/core/errors/README.md — pour les entrées d'erreur marquées @docs, qui sont de la documentation utilisateur finale.
• TSDoc — la référence des balises pour les commentaires de documentation TypeScript.