Commentaires épurés

Objectif

Conserver le minimum de commentaires de haute valeur nécessaire pour rendre une base de code plus facile et plus sûre à comprendre et à maintenir.

La valeur par défaut est pas de commentaire.

Un commentaire doit préserver des informations significatives qu'un mainteneur compétent ne peut raisonnablement pas récupérer à partir du code, des noms, des types, des signatures, de la structure, des tests, de la configuration ou du contexte environnant.

Les commentaires ne sont pas des étiquettes, des narrations, des décorations, des résumés de déclarations, des journaux de modifications ou des substituts à du code clair.

Modèle de lecteur

Écrivez pour un mainteneur compétent qui lit le repository à HEAD plusieurs mois plus tard, sans accès à la conversation actuelle, au prompt, au diff, à la pull request, à la discussion sur les issues, à la discussion de review ou au processus d'implémentation.

Documentez l'état durable, le contrat, la contrainte ou la raison d'être du code tel qu'il existe. Ne supposez pas que le lecteur sait ce qui a changé, ce qui s'est passé avant ou ce qui a été discuté, sauf si ce contexte est délibérément préservé dans une source fiable du projet.

Autorité et preuve

Utilisez cette skill comme autorité en matière de politique de commentaires quand elle est active.

Utilisez les skills de langage, framework, bibliothèque ou infrastructure pour déterminer si une contrainte non-évidente est réelle, pas pour contourner le test de nécessité de cette skill.

Respectez les exigences explicites du repository actuel, les exigences de documentation d'API publique, les contrats d'outils et les règles de source générée. N'inférez pas une exigence de documentation simplement à partir de la densité de commentaires existants ou du précédent.

Basez la rationale conservée ou nouvellement écrite sur des preuves du repository, des tests, de la configuration, du comportement officiel de l'API, de la documentation du projet, du suivi des issues, des ADRs, des spécifications ou d'une autre source fiable.

Ne jamais inventer une raison de sécurité, une raison de performance, une règle métier, une exigence de compatibilité, une contrainte d'API, une raison historique, une raison architecturale ou une limitation externe pour justifier un commentaire.

S'il n'existe pas de raison non-évidente soutenue, supprimez ou omettez-le.

Règle de décision centrale

Avant de conserver ou d'ajouter un commentaire ordinaire, supprimez-le mentalement et posez-vous la question :

Un mainteneur compétent perdrait-il des informations significatives et non-évidentes si ce commentaire n'existait pas ?

Si non, supprimez ou omettez-le.

En cas d'incertitude, préférez pas de commentaire à moins que les preuves du repository ne démontrent que l'information importe.

Si oui, conservez uniquement les informations minimales nécessaires.

Ne conservez jamais un commentaire simplement parce qu'il est correct, inoffensif, déjà présent, bien écrit grammaticalement, écrit comme un avertissement, lié à la sécurité ou à la validation, lié à un état interne ou public, ou attaché à une déclaration exportée.

L'information elle-même doit justifier le commentaire.

Ordre de décision

Évaluez les commentaires existants et proposés dans cet ordre :

1. Supprimer ou omettre si l'information est déjà claire sans lui
2. Exprimer par le code si une minuscule amélioration de lisibilité préservant le comportement supprime le besoin de commentaire
3. Raccourcir s'il est nécessaire mais contient des informations ou des mots inutiles
4. Réécrire s'il est nécessaire mais peu clair, inexact, obsolète, maladroit ou incohérent
5. Utiliser la documentation de déclaration si l'information appartient au contrat, à la sémantique ou à l'usage prévu de la déclaration
6. Conserver inchangé uniquement s'il est déjà nécessaire, minimal, exact, durable et correctement stylisé

Décidez toujours de la nécessité avant de la formulation.

Ne polissez pas un commentaire inutile ou ne le convertissez pas en documentation.

Ce qui mérite un commentaire d'implémentation

Utilisez un commentaire d'implémentation quand il préserve des informations non-évidentes telles que :

• Pourquoi du code intentionnellement surprenant existe
• Une contrainte externe ou un besoin de compatibilité
• Un invariant important ou un cas liminal subtil
• Un compromis significatif ou un contournement requis
• Un couplage non-évident
• Une contrainte d'ordre, de synchronisation, de cycle de vie, de concurrence, de performance ou de sécurité
• Une raison pour laquelle une implémentation apparemment plus simple serait incorrecte

Préférez les commentaires qui expliquent pourquoi quelque chose importe.

Les commentaires qui expliquent simplement quoi le code fait doivent normalement être supprimés.

Supprimer les commentaires de faible valeur

Supprimez les commentaires qui simplement :

• Reformulent ou traduisent le code en prose
• Narrent l'instruction suivante ou un flux de contrôle évident
• Expliquent une clause de garde évidente, un retour, une affectation ou une branche
• Décrivent une récupération évidente, une validation, une transformation, un mappage, un filtrage, une création, une mise à jour ou une suppression
• Répètent un nom de déclaration, un nom de propriété, un type, une signature, un paramètre ou un type de retour
• Étiquettent ou résument une déclaration
• Répètent des informations déjà représentées clairement par les tests ou la configuration
• Ajoutent un contexte générique immédiatement inférieur
• Agissent comme des en-têtes de section inutiles ou des séparateurs visuels
• Préservent l'historique de modification obsolète
• S'adressent au reviewer ou justifient le changement actuel
• Énoncent une règle ou une interdiction nue sans contexte non-évident utile
• Ajoutent une emphase rhétorique sans information

Des mots comme Never, Always, Important, Security, Internal, Public ou Required ne rendent pas un commentaire précieux.

Jugez l'information, pas à quel point la formulation sonne sérieuse.

Préférer du code auto-explicatif

Quand un commentaire compense du code inutilement confus, envisagez une minuscule amélioration locale préservant le comportement, comme améliorer un nom local, extraire un booléen clairement nommé, simplifier le flux de contrôle local ou supprimer la structure locale redondante.

Gardez ces changements minimaux et directement liés à la clarté.

Ne transformez pas le nettoyage de commentaires en une refonte générale ou ne changez le comportement, l'architecture, les API publiques, les dépendances ou du code non lié simplement pour éliminer des commentaires.

Formes de commentaires et de documentation

Appliquez le même test de nécessité entre les langages et syntaxes.

Les formes pertinentes peuvent inclure :

• Les commentaires de ligne et de bloc comme //, #, -- et /* ... */
• JSDoc, TSDoc, JavaDoc, KDoc, commentaires doc Rust, commentaires doc Go, documentation XML C#, et documentations de déclaration équivalentes
• Documentation de module, package et fichier
• Docstrings Python et autres documentations de déclaration représentées comme des chaînes visibles à l'exécution
• Marqueurs TODO, FIXME, NOTE, HACK, XXX et similaires
• Directives consommées par machine, compilateur, formateur, couverture, build, framework, générateur

Ne traitez pas le texte ressemblant à un commentaire à l'intérieur de littéraux de chaîne, d'expressions régulières, d'URLs, d'instantanés, de fixtures, de modèles ou de données de test comme des commentaires source simplement parce qu'ils contiennent une syntaxe de commentaire.

Commentaires d'implémentation

Utilisez la forme de commentaire d'implémentation normale du langage pour une rationale brève, des contraintes, des invariants, des contournements ou d'autres contextes locaux non-évidentes.

Préférez une ligne concise quand une ligne suffit.

Documentation de déclaration

Utilisez la forme de documentation de déclaration du langage uniquement quand l'information appartient à la déclaration elle-même et constitue part de son contrat, de sa sémantique ou de son usage prévu.

Pour TypeScript, utilisez la documentation compatible TSDoc quand justifié. Pour JavaScript, suivez les conventions JSDoc intentionnelles du repository. Pour les autres langages, suivez les vraies conventions de documentation du langage et du repository sans créer de couverture pour elle-même.

Documentation de module et de fichier

Ajoutez une documentation de niveau module, package ou fichier uniquement pour un concept architectural durable, une limite, un invariant, une terminologie, une règle de cycle de vie ou une raison de conception qui ne sont pas apparents à partir du contenu.

N'ajoutez pas d'en-têtes de fichier qui résument simplement les exports ou décrivez un objectif de fichier évident.

Documentation visible à l'exécution

Certaines formes de documentation, notamment les docstrings Python, peuvent être observables à l'exécution via l'introspection ou les outils.

Avant de supprimer ou de modifier matériellement la documentation visible à l'exécution, vérifiez que cela ne change pas un contrat d'exécution soutenu, une surface de documentation générée ou une attente d'API externe.

Règles de documentation de déclaration

Ceci n'est pas un exercice de couverture de documentation.

Ne documentez pas les déclarations simplement parce qu'elles sont exportées ou publiques, et ne supposez pas que chaque export au niveau du langage dans du code d'application est une API externe intentionnellement soutenue.

Utilisez la documentation de déclaration quand les consommateurs ou les mainteneurs ont besoin d'informations non-évidentes sur :

• Les contrats de comportement, les contraintes de paramètre, la sémantique de retour ou les valeurs spéciales
• Le comportement d'erreur, les effets secondaires, les préconditions ou postconditions
• L'ordre, la synchronisation, le cycle de vie, la concurrence ou le comportement de cache
• Les contraintes de sécurité, d'exécution, de serveur, de client, de SSR ou d'environnement
• Les exigences de compatibilité ou le comportement d'API en amont
• Les règles métier ou invariants
• Les unités, formats, plages, encodages ou relations entre champs
• La dépréciation, les points d'extension ou les restrictions d'usage importantes
• L'usage non-évident qui bénéficie matériellement d'un exemple

Appliquez un biais de documentation plus fort aux bibliothèques publiées, SDKs, packages, plugins, APIs d'extension et interfaces intentionnellement externes.

Appliquez un biais de non-documentation plus fort aux helpers internes, aux simples méthodes CRUD, aux adaptateurs simples, aux composables, aux formes de données simples, aux DTOs et aux utilitaires internes.

Ne répétez pas le système de type

N'ajoutez pas de documentation qui reformule simplement les noms, types, signatures, valeurs évidentes ou structure déjà exprimées par le langage.

Ne mécaniquement les balises @param, @returns, @throws, @example, @remarks ou @see. Utilisez une balise uniquement quand elle contribue des informations au-delà de la déclaration et du système de type.

Les interfaces simples, les enregistrements, les DTOs, les structs, les types et les formes de données évidentes ne nécessitent normalement aucune documentation à moins qu'ils contiennent une sémantique non-évidente, des invariants, des formats, des unités, des relations, des contraintes externes ou des exigences de compatibilité.

Style

Commentaires d'implémentation de prose sur une ligne

Pour un commentaire d'implémentation de prose sur une ligne nécessaire, quel que soit le délimiteur de commentaire :

• Gardez-le aussi court que possible sans le rendre cryptique
• Commencez la prose normale avec une lettre majuscule sauf si la casse techniquement requise dicte autrement
• Ne le terminez pas par ., !, ? ou autre ponctuation de phrase terminale
• N'utilisez pas de tirets cadratins ou de demi-tirets
• N'utilisez pas de ponctuation de phrase basée sur des tirets
• N'utilisez pas de points-virgules comme ponctuation de phrase
• Préférez une clause concise à la prose inutilement complète
• Préservez la casse exacte et la ponctuation dans les identifiants, le code, les commandes, les URLs, les chemins, les noms de package, les versions, les valeurs d'API et autres littéraux techniques

Exemple :

// Preserve source order for positional matching

Pas :

// Preserve source order for positional matching.

Ces règles de prose ne s'appliquent pas à la syntaxe consommée par machine, à la ponctuation techniquement significative ou à la véritable documentation de déclaration multi-ligne.

Documentation de déclaration

Utilisez la ponctuation de phrase normale pour la véritable documentation de déclaration multi-phrase.

Gardez-la concise et focalisée sur les informations de contrat ou de sémantique significatives. N'ajoutez pas de prose, de balises, d'exemples ou de sections simplement pour que la documentation paraisse complète.

Exemples de haute valeur

<examples>

<example> Supprimer :

// A watchlist row
export interface FlickWatchlistItem {
  media: FlickMedia;
  added_at: string;
}

Correct :

export interface FlickWatchlistItem {
  media: FlickMedia;
  added_at: string;
}

La déclaration communique déjà le concept. Ne raccourcissez pas le commentaire ou ne le convertissez pas en documentation de déclaration. </example>

<example> Habituellement supprimer :

// Never copy a raw internal message into the public response

Ne conservez pas ceci simplement parce qu'il contient Never ou concerne une limite publique.

Si les preuves du repository établissent une raison véritablement non-évidente, conservez uniquement cette raison soutenue :

// Keep provider errors private because messages may contain credentials

Ne jamais inventer une telle rationale pour sauver le commentaire original. </example>

<example> Supprimer :

// Return the normalized result
return normalize(result);

Le code communique déjà l'action. </example>

<example> Conserver quand soutenu par l'implémentation ou le contrat externe :

// Preserve source order because the upstream API matches items by position

Le commentaire communique une contrainte positionnelle non-évidente. </example>

<example> Documentation de déclaration utile :

/**
 * Returns `null` for private profiles instead of propagating the upstream authorization error.
 */
export async function getProfile(): Promise<Profile | null> {
  // ...
}

La documentation explique un comportement visible pour l'appelant que le type seul ne peut pas communiquer. </example>

</examples>

Marqueurs TODO, FIXME, NOTE et similaires

Traitez les marqueurs TODO, FIXME, NOTE, HACK, XXX et équivalents comme des commentaires, pas comme des exceptions.

Vérifiez que chacun est toujours pertinent, techniquement exact, utile et actionnable le cas échéant. Suivez les conventions du repository pour les références ou la propriété d'issues quand de telles conventions existent réellement.

Supprimez les marqueurs obsolètes, complétés, insignifiants ou remplacés.

N'ajoutez pas un préfixe de marqueur simplement pour rendre un commentaire ordinaire important.

N'implémentez pas du travail non lié simplement pour supprimer un marqueur valide.

Code commenté

Le code exécutable commenté est normalement du code mort.

Supprimez-le quand le contrôle de version préserve déjà l'historique et qu'il n'existe aucune raison actuelle pour que le code désactivé reste.

Conservez-le uniquement quand la forme désactivée sert un objectif soutenu actuel, comme un exemple copyable délibéré, une fixture sémantiquement significative, un fallback de compatibilité documenté que les mainteneurs sont censés réactiver sous une condition connue, ou une syntaxe d'outils/framework qui doit rester désactivée dans le formulaire source.

Ne conservez pas le code commenté simplement parce qu'il pourrait être utile plus tard.

Ne décommentez ou n'exécutez du code ancien simplement pour justifier de le conserver.

Directives et en-têtes techniquement significatifs

Préservez les constructions dont la présence, la position ou la syntaxe exacte a une importance technique, d'outils, de génération, d'exécution ou juridique, incluant le cas échéant :

• Shebangs
• Directives de lint et de formateur
• Directives du compilateur et du type-checker
• Directives de couverture
• Balises de build et pragmas
• Directives de framework
• Annotations de bundler ou d'optimiseur
• Directives source-map et sourceURL
• Marqueurs générés
• Annotations requises
• Déclarations d'encodage
• En-têtes de licence et copyright
• Autres commentaires consommés par machine

Ceux-ci ne sont pas des commentaires de prose ordinaires. N'appliquez pas les règles de formatage de prose à leur syntaxe et préservez la ponctuation techniquement requise exactement.

Directives obsolètes

Les directives techniquement significatives sont protégées uniquement tant qu'elles restent nécessaires.

Quand c'est pratique, vérifiez si les suppressions et autres directives d'outils sont toujours requises. Supprimez une directive quand les preuves du repository ou l'outil pertinent prouvent qu'elle est obsolète.

Ne supprimez ou ne réécrivez pas une directive unfamilier simplement parce que son objectif est peu clair. Vérifiez-le d'abord.

Ne élargissez pas une suppression. Réduisez ou supprimez-la uniquement quand le changement est clairement sûr, directement lié à l'audit et n'exige pas de refonte non liée.

Traitez les en-têtes juridiques plus conservativement que les directives d'outils. Ne supprimez ou n'altérez pas le texte de licence ou de copyright sans autorité claire du projet.

Références durables et liens

Une URL d'issue, pull request, spécification ou documentation nue n'est pas automatiquement un commentaire utile.

Conservez ou ajoutez une référence uniquement quand elle préserve matériellement un contexte non-évident qui ne peut pas être exprimé suffisamment clairement dans le code seul.

Préférez un contexte concis durable plus une référence stable quand la source externe contient des détails importants qui seraient déraisonnables de dupliquer.

Ne comptez pas sur le contexte de conversation transitoire ou un fil de review inaccessible comme seule explication pour du code surprenant.

Édition du code existant

Traitez les commentaires existants comme non fiables. Le fait qu'ils aient survécu aux passes de nettoyage précédentes ne rend pas un commentaire correct ou nécessaire.

Quand les changements de code rendent les commentaires inexacts ou redondants, mettez-les à jour ou supprimez-les dans le même changement.

Ne narrez pas l'historique de modification avec des phrases comme now, previously, new approach, old behavior ou no longer.

Documentez l'état durable à la place.

Ne vous adressez pas au reviewer ni ne faites référence à la conversation actuelle, au prompt, au diff, à la pull request ou au processus d'implémentation.

Interaction avec les skills de raffinement de prose

Quand une skill de raffinement de prose comme unslop est disponible, lean-comments reste faisant autorité.

Utilisez le raffinement de prose uniquement après avoir déterminé que le commentaire mérite d'exister.

L'ordre est :

1. Déterminez la nécessité
2. Supprimez s'il est inutile
3. Déterminez la forme correcte du commentaire
4. Minimisez l'information
5. Affinez la formulation

Le raffinement peut améliorer la clarté, le naturalisme et la lisibilité, mais ne doit pas introduire de personnalité ou de voix pour elle-même, de flourish rhétorique, d'humour, de remplisseur conversationnel, de rationale supplémentaire, d'exemples supplémentaires, de réclamations supplémentaires, d'augmentation de verbosité ou d'information qui n'était pas déjà justifiée.

Préférez la formulation la plus courte naturelle qui préserve le sens technique nécessaire.

Ne laissez pas une skill de raffinement de prose affaiblir les exigences de cette skill pour la nécessité, le minimalisme, la précision, la durabilité ou le style.

Un commentaire inutile poli est toujours inutile.

Travail d'implémentation normal

Quand vous ajoutez ou modifiez du code :

• N'ajoutez pas de commentaires par défaut
• Ajoutez-en un uniquement s'il passe le test de nécessité
• Appliquez cette skill aux commentaires directement affectés par l'implémentation
• Supprimez les commentaires rendus obsolètes par le changement
• Ne effectuez pas un nettoyage de commentaires non lié à l'échelle du repository à moins que cela ne soit demandé

Audits à l'échelle du repository

Quand on vous demande explicitement d'auditer les commentaires dans tout un repository :

1. Inspectez suffisamment du repository pour comprendre sa terminologie, son architecture, ses langages, ses outils, ses contraintes externes et ses conventions de documentation
2. Identifiez l'étendue first-party maintenue et excluez le contenu généré, vendorisé, de dépendances, tiers et externalement maintenu
3. Cherchez systématiquement toutes les formes de commentaire, documentation, marqueur, directive et code commenté pertinentes utilisées par les langages du repository
4. Examinez les commentaires non touchés par les passes de nettoyage précédentes
5. Appliquez le test de nécessité avant de faire des changements de formulation
6. Examinez la documentation de déclaration aussi critiquement que les commentaires ordinaires
7. Examinez les commentaires immédiatement précédant les déclarations pour les étiquettes ou résumés redondants
8. Examinez TODO, FIXME, NOTE, HACK, XXX, directives d'outils, suppressions et code commenté
9. Inspectez le diff final pour les changements de comportement, formatage ou non lié accidentels
10. Cherchez à nouveau pour les violations probablement manquées
11. Exécutez la validation pertinente du repository quand les fichiers source ou directives ont changé

Pour les commentaires de prose sur une ligne, inspectez spécifiquement les commentaires restants se terminant par ., ! ou ?.

Ne modifiez pas aveuglément les correspondances. Excluez la syntaxe techniquement significative et le texte ressemblant à un commentaire qui est réellement des données.

Pour les directives et suppressions, utilisez l'outil pertinent quand c'est pratique pour distinguer les contrôles requis des contrôles obsolètes.

Limites d'étendue

Appliquez cette skill au contenu source first-party maintenu.

Ne modifiez pas le contenu généré, vendorisé, de dépendances, tiers, externalement maintenu ou machine-généré à moins que la synchronisation avec un changement de source intentionnel ne l'exige.

N'introduisez pas de changements fonctionnels, architecturaux, de comportement, de dépendances, de formatage large ou de refonte non lié.

Gardez le diff résultant focalisé.

Vérification d'acceptation finale

Avant de compléter un audit à l'échelle du repository, vérifiez que :

• Chaque commentaire ordinaire restant contribue des informations significatives non-évidentes
• Les commentaires évidents ont été supprimés plutôt que polis
• Les commentaires d'étiquettes, la narration de code et les avertissements nus ont disparu
• Les commentaires sont aussi concis que possible sans devenir cryptiques
• Les commentaires de prose sur une ligne suivent les règles de style ci-dessus
• La documentation de déclaration ajoute des informations véritables de contrat ou de sémantique
• Les déclarations de données simples ne sont pas décorées avec de la documentation inutile
• Les types et signatures ne sont pas répétés inutilement
• Aucune rationale ou historique n'a été inventé
• Les marqueurs TODO, FIXME, NOTE, HACK, XXX et équivalents obsolètes ont disparu
• Le code commenté injustifié a disparu
• Les constructions machine-significatives requises restent intactes
• Les directives d'outils et suppressions prouvées-obsolètes ont disparu
• La documentation visible à l'exécution n'a pas été supprimée sans vérifier son contrat
• Le texte ressemblant à un commentaire n'a pas été pris pour un commentaire source
• Aucun changement non lié n'a été introduit
• La validation pertinente passe

Si un nettoyage à l'échelle du repository consiste toujours principalement en changements de formulation ou de ponctuation tandis que presque tous les commentaires originaux survivent, réévaluez la nécessité.

N'optimisez pas pour un nombre ou un pourcentage cible de commentaires.

Arrêtez quand la suppression ou le raccourcissement supplémentaire supprimerait véritablement des informations utiles plutôt que de réduire simplement le nombre de commentaires.