Créer une bibliothèque de données aux API faciles à trouver, testée sur des valeurs réelles

## Cacher des données sources complexes derrière des objets simples Masquez la complexité du format source derrière des objets métier intuitifs sans dissimuler les capacités importantes. Rendez les opérations courantes directes, puis présentez progressivement les fonctions spécialisées d’analyse, de production de rapports et d’inspection lorsque les utilisateurs en ont besoin. Lisez avant d’écrire. Avant de modifier du code, examinez les abstractions existantes, les conventions de nommage, les frontières entre modules et les tests voisins. Étendez la conception actuelle, sauf si une incompatibilité concrète exige un nouveau modèle. ## Avant de modifier, repérer quel module gère chaque tâche Maintenez une carte de navigation concise qui relie les besoins des utilisateurs aux modules responsables et aux principales classes métier. Incluez les points d’entrée publics permettant de localiser des enregistrements, de charger des entités, d’analyser des données structurées, de construire des états, de lire des notes, d’ouvrir des documents et de créer des rapports typés. Avant toute modification, suivez de bout en bout des flux de données représentatifs. Accompagnez une demande depuis son point d’entrée public à travers la récupération, l’analyse, les objets typés, les états, les notes, les rapports et l’extraction de documents. Confirmez quelle couche est responsable de chaque transformation et à quel endroit les utilisateurs doivent approfondir leur recherche pour obtenir les détails justificatifs. Utilisez la carte pour choisir le plus petit module responsable. Ne placez pas un comportement dans un fichier simplement pratique lorsqu’une autre couche en est déjà responsable. ## Lire les gros fichiers par morceaux et les modifier de façon ciblée Traitez les modules de plus de 30 KB comme plusieurs contextes locaux plutôt que de les lire ou de les réécrire en un seul bloc. Recherchez le symbole pertinent, examinez la classe ou la fonction qui le contient, puis lisez suffisamment de code voisin pour comprendre les invariants et les points d’appel. Avant de modifier un fichier volumineux, localisez les tests, les importations, les sous-classes et les références publiques associés. Limitez étroitement la modification, respectez les conventions environnantes et évitez toute remise en forme ou restructuration sans rapport qui masquerait le changement fonctionnel. ## Consigner et mettre à jour le travail dans les tickets Utilisez le système de suivi des tickets du projet comme registre durable du travail actif. Examinez les éléments ouverts et en cours, sélectionnez le ticket pertinent, puis faites-le passer à l’état actif avant l’implémentation. Enregistrez les défauts ou les tâches nouvellement découverts avec un titre, un type et une priorité explicites, au lieu de les laisser uniquement dans des commentaires ou des discussions. Mettez à jour le même ticket lorsque la portée, les obstacles ou les conclusions changent. Ne le clôturez qu’après l’achèvement de la vérification requise. Conservez les états définis `open`, `in-progress`, `blocked` et `closed`. Lorsque le système utilise cinq niveaux de priorité, réservez `0` au travail critique et `4` au travail en attente, au lieu d’inventer des libellés improvisés. ## Vérifier que la bibliothèque tient les promesses de sa documentation La vérification cherche à déterminer si la bibliothèque tient les promesses de sa documentation, et pas seulement si son code interne s’exécute. Appliquez trois principes directeurs : 1. La documentation constitue la spécification ; chaque exemple documenté doit donc être vérifiable. 2. L’exactitude des données est essentielle ; les contrôles doivent donc affirmer des valeurs attendues précises plutôt que leur simple existence. 3. L’API doit permettre de résoudre le problème ; utilisateurs et agents doivent donc pouvoir passer d’une question à l’objet, à la méthode et aux preuves justificatives appropriés. Utilisez ces principes pour évaluer ensemble la conception de la fonctionnalité, la documentation, les cas de test et le comportement en cas d’échec. ## Donner à chaque nouvelle fonction un test sur des valeurs réelles et un exemple exécutable dans la documentation Toute nouvelle fonctionnalité destinée aux utilisateurs doit inclure : - une assertion fondée sur une valeur de référence précise provenant d’un enregistrement source réel et vérifiée indépendamment ; - un exemple documenté qui s’exécute également comme une vérification automatisée ; - un contrôle des échecs silencieux prouvant qu’une entrée invalide ou absente produit une erreur utile plutôt qu’une valeur vide ou un échec sans indication ; - une mise à jour facilitant sa découverte, afin que la fonctionnalité apparaisse dans la navigation du projet, le catalogue des capacités ou les consignes destinées aux agents. La fonctionnalité reste incomplète s’il manque l’un de ces éléments, même si son implémentation fonctionne dans le parcours nominal. ## Lancer d’abord les tests locaux rapides, puis les tests réseau un par un Fournissez des commandes distinctes pour la vérification locale rapide, la vérification réseau, la vérification des régressions et les rapports de couverture. Exécutez d’abord le plus petit contrôle local pertinent, puis élargissez sa portée uniquement lorsque le résultat ciblé est concluant. Ne parallélisez que les tests rapides qui ne contactent aucun service externe. Exécutez les vérifications réseau de manière séquentielle et respectez les limites de débit du service. Utilisez des jeux de réponses enregistrées lorsqu’ils peuvent rendre le comportement externe rapide et déterministe sans masquer le contrat vérifié. Placez les cas de régression dans une zone dédiée, avec des noms stables reliant chaque cas au défaut dont il provient. Traitez la couverture comme une preuve complémentaire, et non comme un substitut aux assertions portant sur le comportement et les données. ## Vérifier des valeurs exactes et des erreurs claires avec des données variées Affirmez des valeurs métier exactes, des structures normalisées et des messages d’erreur significatifs. Une assertion qui vérifie seulement l’existence d’un résultat ne suffit pas lorsque l’exactitude dépend de la valeur elle-même. Diversifiez les enregistrements sources entre organisations, secteurs, formats et périodes de déclaration, au lieu de vous appuyer sur un seul exemple familier. Testez explicitement les entrées mal formées, incomplètes et non prises en charge. Confirmez que les échecs renvoient des messages exploitables et ne se transforment jamais silencieusement en un résultat vide. Lorsque des données externes sont nécessaires, conservez des jeux de test déterministes et documentez comment leurs valeurs attendues ont été établies. Actualisez-les délibérément lorsque le contrat amont change ; ne les renouvelez pas uniquement pour faire réussir un contrôle en échec. ## Garder la version et la documentation alignées sur le code qui fonctionne Lisez la version du projet depuis le fichier de métadonnées désigné et évitez de la dupliquer dans des modules sans rapport. Maintenez la navigation du dépôt, les consignes de vérification, les exemples publics et les catalogues de capacités en phase avec le comportement pris en charge. Lorsqu’un chemin de l’API change, mettez à jour la documentation et les exemples exécutables dans le même élément de travail. Un chemin documenté qui ne fonctionne plus rompt le contrat destiné aux utilisateurs, même si l’implémentation de remplacement est correcte.