antislop-code

Anti Slop : Règles pour les agents de codage IA. Compétence sur les commentaires de code

Fait partie du système antislop. À lire conjointement avec antislop.md (le noyau). Cette compétence filtre les commentaires qui ressemblent à du texte générique produit par l'IA (décoratif, redondant, rigide, bruyant) tout en conservant les commentaires porteurs d'informations réelles. Elle cite les règles centrales par numéro et ne les duplique ni ne les renumérote jamais. Chargez-la lorsque la tâche écrit ou modifie des commentaires de code.

Comment utiliser cette compétence

Chargez-la avec antislop.md dès que la tâche touche aux commentaires de code. Le noyau contient le mécanisme (le test d'intention, les trois niveaux, le Portail de Livraison) ; cette compétence contient la profondeur spécifique aux commentaires.
Chaque entrée a la même forme : Dire (le motif), Pourquoi (pourquoi il ressemble à du slop), Correction (quoi faire à la place), avec la règle centrale correspondante citée comme R-XX.
Garde-fou de périmètre : cette compétence ne modifie que les commentaires. Ne modifiez jamais le code exécutable, les identifiants, les imports, le formatage, l'indentation, les espaces blancs, le flux de contrôle ou la logique. En cas de doute, laissez le code intact.
Le Portail de Livraison du noyau reste le portail. La « Checklist des commentaires de code » à la fin de ce fichier est le supplément spécifique aux commentaires à exécuter en parallèle.

Commentaires qui n'apportent rien

Séparateurs décoratifs

Dire : commentaires-bannières construits avec des caractères répétés, des étiquettes EN MAJUSCULES, ou un encadrement autour d'un nom de section : // ======================= autour de Authentication, // -------- WORKFLOW --------, ou une en-tête /* ---- ROUTES ---- */.
Pourquoi : la décoration est le message. Une étiquette entourée de = ou - signale « fait par l'IA » sans ajouter d'information, et les MAJUSCULES donnent l'impression de crier.
Correction : remplacez par une seule ligne simple, ou supprimez complètement si l'étiquette n'ajoute rien (R-31).

Redite de l'évidence

Dire : un commentaire qui répète ce que la ligne ou la déclaration suivante montre déjà, comme // Initialise la variable au-dessus de let count = 0, // Classe Utilisateur au-dessus de class User {}, // Valide l'utilisateur au-dessus de function validateUser(), ou const userAge = 25; // L'âge de l'utilisateur est 25.
Pourquoi : cela double la charge de lecture sans rien apporter. Le code le dit déjà ; le commentaire ne fait que répéter.
Correction : supprimez et laissez la ligne de code telle quelle.

Narration du flux de travail

Dire : des commentaires qui narrent le flux étape par étape, comme // Étape 1 : Valider l'entrée, // Étape 2 : Traiter la requête, // Étape 3 : Renvoyer la réponse, ou // D'abord..., // Ensuite..., // Enfin....
Pourquoi : le flux de contrôle est visible dans le code lui-même. Le numéroter donne l'impression d'une liste de contrôle, pas d'une explication.
Correction : supprimez. Si le flux est vraiment difficile à suivre, c'est un problème de structure, pas un problème de commentaire manquant.

Étiquettes vides

Dire : des étiquettes génériques sans information derrière : // Logique principale, // Logique métier, // Fonction utilitaire, // Point d'entrée, // Gestion des erreurs, ou // Note : Ceci est important. / // Important : Veuillez lire.
Pourquoi : l'étiquette nomme une catégorie, pas un fait. « Logique principale » n'apprend rien au lecteur qu'il n'aurait pu déduire du code.
Correction : supprimez sauf si l'étiquette porte une information spécifique. « Note : les nouvelles tentatives n'ont lieu qu'en cas de 5xx » mérite sa place ; « Note : ceci est important » non.

Espaces réservés vagues

Dire : des commentaires qui promettent du travail futur sans dire quoi : // TODO : Améliorer ceci, // Améliorations futures, // Une optimisation supplémentaire peut être ajoutée ici, // Ajouter plus de validation.
Pourquoi : un TODO vague est du bruit. Il nomme un sentiment (ça pourrait être mieux) au lieu d'une tâche (quoi, et pourquoi).
Correction : supprimez. Ne conservez un TODO que lorsqu'il nomme une tâche spécifique avec suffisamment de contexte pour agir.

Écho de signature

Dire : une documentation qui ne fait que répéter la signature, comme un bloc JSDoc qui répète @param prix Le prix. et @returns Prix total. pour une fonction dont le nom et les paramètres disent déjà tout.
Pourquoi : les docs qui font écho à la signature ajoutent de la longueur, pas de la compréhension. Le lecteur n'apprend rien de nouveau.
Correction : simplifiez ou supprimez l'écho. Conservez la documentation qui explique les règles métier, les cas particuliers, les hypothèses, les algorithmes, les limitations, les effets de bord, le comportement de l'API ou les implications de sécurité. Ne supprimez jamais la documentation réelle.

Émojis décoratifs

Dire : des émojis utilisés comme décoration dans les commentaires, comme // ✅ Validation ou // 🚀 Performance.
Pourquoi : les émojis sont du bruit visuel dans le code, et l'ensemble spécifique (✅, 🚀, 🔒) est le vocabulaire par défaut de l'IA.
Correction : remplacez par du français simple, ou supprimez si l'étiquette n'ajoute rien.

Marqueurs de fin

Dire : des commentaires qui marquent uniquement la fin d'un bloc, comme } // fin si, # Fin de la fonction, ou // Fin traiterCommande.
Pourquoi : l'accolade fermante termine déjà le bloc. Le marqueur existe par habitude, pas par nécessité.
Correction : supprimez. Dans les rares cas où un marqueur de fin aide vraiment dans un fichier long, ne le conservez que là où il évite une confusion, pas par habitude.

Comment ça devrait se lire

Le commentaire trop expliqué

Dire : un commentaire qui s'étend sur plusieurs lignes, empilant raisons, contexte et historique autour d'un fait qui tient en une ligne : un bloc de quatre lignes expliquant qu'un stub se trouve sur le PATH, quelle version a introduit la solution de contournement, et ce qui cassait avant. Chaque phrase est vraie. La longueur est l'indice.
Pourquoi : une personne laisse une note, un générateur écrit un cas. Remplir un fait d'une ligne en un paragraphe, construire une chaîne « parce que X, donc Y, et par conséquent Z », ou citer le numéro de l'issue et la version qui l'a corrigée sont les mêmes fioritures que tout autre motif d'IA, et ils enterrent la ligne qui compte sous celles qui ne comptent pas.
Correction : réduisez à la seule contrainte : une ligne, deux au maximum, jamais trois. Conservez le piège de plateforme, l'échec silencieux, la règle de protocole, le coût de performance. Supprimez le numéro d'issue, l'historique des versions et la chaîne de raisonnement.

Narration ligne par ligne

Dire : un commentaire sur chaque instruction triviale, narrant chaque ligne au fur et à mesure : // Initialise le compteur, puis // Parcourt les éléments, puis // Obtient l'élément, puis // Incrémente, puis // Renvoie le résultat.
Pourquoi : quand chaque ligne est commentée, aucun commentaire n'a d'importance. Le lecteur doit tous les vérifier pour trouver celui qui a du sens.
Correction : écrivez un commentaire concis par bloc logique au lieu d'un par ligne. Si le bloc n'a pas besoin de commentaire, n'en écrivez aucun.

Formulation rigide ou bruyante

Dire : des commentaires qui semblent formels, longs, ou crient : « Cette fonction est responsable de la validation des informations d'identification fournies avant de continuer le processus d'authentification », ou // LOGIQUE PRINCIPALE en majuscules.
Pourquoi : une formulation formelle et bruyante donne l'impression d'être générée, pas celle d'un ingénieur laissant une note au suivant.
Correction : écrivez des lignes courtes en minuscules avec une voix de développeur naturelle : // Valide les identifiants avant d'émettre un jeton. Les bons commentaires expliquent pourquoi, pas quoi, et restent courts.

Pas une interdiction (conservez ceux-ci)

Ne supprimez jamais les commentaires qui expliquent :

la logique métier et l'intention
les décisions architecturales
les considérations de sécurité
les compromis de performance
le comportement concurrent
les détails de protocole
les contrats d'API
les solutions de contournement
les cas particuliers et hypothèses
les licences et avis légaux

Exemple qui doit rester :

// Stripe peut renouveler les livraisons de webhook jusqu'à trois jours.
// Ignorez les événements en double en utilisant l'ID de l'événement.

Un commentaire mérite sa place lorsqu'il explique quelque chose que le code ne montre pas déjà : la raison, la contrainte, le comportement non évident.

Mériter sa place dit ce qui peut rester, jamais combien de temps. Une note de contournement est une ligne sur le contournement, pas un paragraphe. L'exemple ci-dessus fait deux lignes parce que deux faits sont réels, pas parce que deux lignes est un objectif. Cette liste est la raison la plus courante pour laquelle un commentaire survit à une révision qu'il ne devrait pas : le contenu est légitimement précieux, donc la longueur reste inexplorée. La valeur n'est pas la longueur.

Checklist des commentaires de code

Exécutez-la en parallèle du Portail de Livraison central lorsque la tâche touche aux commentaires. Toutes les réponses doivent être oui :

yonathan-boop/Claude

Qu'est-ce que Claude ?

Demander à votre IA préférée

Documentation