Garder vos décisions12 / 20
Voir la couverture de vos intentions
Sur cette page
Quelle part de ce logiciel maîtrisez-vous vraiment ? La couverture des intentions répond par une seule image : un carré par fichier de code, rangé par module, et plus le carré est foncé, plus vos explications citent de ses lignes. Ce qui reste vide et les explications périmées apparaissent d’un coup d’œil. Pointez une intention et les fichiers qu’elle couvre s’allument.
Ouvrir la couverture des intentions
Démarrez une nouvelle conversation : avant que vous envoyiez le premier message, la zone de conversation affiche la carte « Couverture des intentions ». Vous pouvez aussi ouvrir Réglages → Couverture des intentions (dans le groupe du projet actuel), où la carte remplit la page, ce qui aide pour les grands projets.
La couverture des intentions exige que le dossier d’implémentation soit un dépôt Git. Tant que le projet n’a pas de résultat de couverture, la carte affiche « Pas encore calculée » et propose deux façons de commencer : « Expliquer » demande d’abord à l’Agent de rédiger des explications, et « Calculer maintenant » calcule la couverture à partir des explications que vous avez déjà. Dans les gros dépôts, il faut lire chaque fichier, ce qui peut prendre du temps.
Ensuite, la carte se met à jour à chaque fin d’Expliquer. À droite de sa ligne de titre figurent la fin du dernier Expliquer et le commit de ce moment, avec un bouton pour recalculer.
Lire la carte
En haut de la carte se trouve un grand nombre : la part de toutes les lignes de code du périmètre que les explications citent. À côté, « 3 / 6 fichiers » indique combien de fichiers ont une intention derrière eux sur le total.
La barre en dessous comporte trois parties, avec une légende sous elle :
- Lignes référencées : la partie pleine, aussi longue que le pourcentage.
- Explication obsolète : la partie hachurée, les fichiers modifiés après la rédaction de leurs explications.
- Sans intention : la partie vide, les fichiers qu’aucune explication ne cite.
Par module
La zone « Modules » affiche par défaut des points : un point par fichier, une rangée par dossier. Les fichiers qui ont une intention derrière eux deviennent plus foncés à mesure que plus de leurs lignes sont citées ; les fichiers dont les explications sont obsolètes sont hachurés ; les fichiers sans intention sont vides. Pointez un point pour voir le nom du fichier et la part qui en est citée.
L’interrupteur en haut à droite transforme les points en barres : une rangée par module, aussi longue que son nombre de lignes, divisée selon les trois états.
Cliquez sur un module pour descendre d’un niveau ; un bouton de retour et le chemin apparaissent dans la ligne de titre. Dans le service d’abonnements, par exemple, les rangées billing, jobs, notify et web sont côte à côte, et la rangée notify est presque vide : les règles des e-mails de notification n’ont pas encore été écrites dans l’intention.
Par intention
Sous les modules se trouve la liste des intentions, une ligne par document d’intention, en retrait comme l’arborescence des documents, avec une courte ligne indiquant à combien de fichiers il correspond. Un document qui n’a encore aucun code derrière lui est grisé, avec une ligne vide.
- Pointer un document : les rangées de la zone des modules qui n’ont rien à voir avec lui s’estompent, et la mise en page reste en place.
- Cliquer sur un document : les rangées sans rapport se replient, la barre et les points n’affichent que le code auquel cette intention correspond, et une pastille portant le nom du document et un × apparaît sous le titre des modules.
- Cliquez de nouveau, cliquez sur le × de la pastille, ou appuyez sur
Escpour l’effacer.
Cliquez sur Renouvellement, par exemple, et il ne reste que billing/grace.ts, jobs/renewal-job.ts et quelques fichiers de test. Vous voyez aussitôt ce que touchera une modification des règles de renouvellement.
Ce que signifie le nombre
La couverture mesure la quantité de code que vos explications citent. Ce n’est ni la qualité du code, ni la couverture des tests. Elle aide à répondre à deux questions :
- Où n’y a-t-il pas encore d’intention ? Un module vide est soit du code qui compte peu, soit des règles déjà en service auxquelles vous n’avez pas réfléchi. Ces dernières méritent un paragraphe d’intention et un Expliquer.
- Où les explications sont-elles obsolètes ? De fortes hachures signalent des changements récents que les explications n’ont pas rattrapés ; voir Quand le code change.
Inutile de viser 100 %. Commencez par ce qui compte le plus pour vous et laissez cette partie foncer d’abord.
Parnas Index
Réglages → Parnas Index regarde la même chose de l’autre côté : jusqu’où les changements de code atteignent votre intention. Le nom vient du principe de décomposition en modules de David Parnas : un bon module cache une décision susceptible de changer. Dans Noea, un passage d’intention représente une décision et un fichier de code un module.
Le grand nombre en haut est le nombre de passages d’intention revérifiés, en moyenne, par fichier modifié, avec combien ont été entièrement vérifiés et combien d’entre eux n’ont pas changé. Plus il est élevé, plus un seul changement entraîne de décisions. La fenêtre de temps peut être de 7, 30 ou 90 jours.
La page propose deux vues :
| Vue | Niveaux | Colonnes |
|---|---|---|
| Combien d'intentions ce code touche | Fichiers, Définitions | Intentions touchées, Modifications, Par modif., Inchangé |
| Combien de code touche cette intention | Documents, Passages | Fichiers cités, Modifs code, Modifs intention, Inchangé |
Cliquez sur une ligne pour l’ouvrir sur place. Une ligne de fichier montre quelle part en est citée par les explications, les intentions qu’il touche le plus, et « Voir dans la couverture des intentions » ; une ligne d’intention montre combien de fichiers elle cite, le code qui l’atteint le plus, et un moyen d’ouvrir ce passage.
Sous le niveau des fichiers de la première vue se trouve un nuage de points « Couverture et portée » : en abscisse, la part des lignes citées par les explications ; en ordonnée, le nombre de passages d’intention que chaque changement atteint. Les fichiers en haut à droite sont densément cités et souvent modifiés, si bien que chaque changement oblige à revérifier beaucoup d’intention ; il peut valoir la peine de les découper. Une couverture plus élevée n’est pas toujours meilleure.
Si le projet n’a pas encore de dossier d’implémentation lié, les deux pages vous demandent d’en lier un d’abord dans Réglages → Projet.