« Je n'ai pas pu le lire » n'est pas « il n'y a rien »
Chiffres et données
Chaque donnée a trois états : je l'ai, il n'y avait vraiment rien, et je ne sais pas. Les deux derniers se dessinent de la même façon sur un graphique, comme un zéro, alors qu'ils signifient le contraire.
Question détectrice
Le chiffre que je m'apprête à afficher, ou le « tout va bien » que je m'apprête à croire, pourrait-il venir d'une requête échouée, d'une table vide, d'une autorisation refusée, ou d'un résultat que je n'ai pas lu en entier (voir la leçon 44) ?
Signal d'alarme
« Si ça échoue, je mets zéro et je passe à autre chose. »
Exemple et quoi faire
Exemple
Une requête échoue à cause d'une autorisation expirée, et le tableau de bord affiche « 0 ventes » pour la région. Personne ne s'en étonne : un zéro a l'air d'une donnée.
Que faire
Si la lecture échoue, affichez l'erreur sur la carte elle-même, et non un vide ou un zéro. Et un compteur qui affiche « 0 problème » n'est digne de confiance que s'il a d'abord trouvé un problème que vous aviez placé exprès.
Deux choses qui portent le même nom ne sont pas la même chose
Chiffres et données
« Client actif », « date », « le chef », « le seuil » : le même mot cache souvent deux définitions. Quand deux rapports ne concordent pas, c'est presque toujours cela.
Question détectrice
Existe-t-il une règle vraie pour l'une des deux choses et fausse pour l'autre ? Et si je combine deux chiffres dans un même calcul, viennent-ils du même univers, de la même échelle et de la même période ?
Signal d'alarme
« C'est la même date » · « la vue filtre déjà » · « ce sont tous les deux en pesos ».
Exemple et quoi faire
Exemple
« Date » peut désigner la date de l'événement, la date de chargement ou la date de la partition. Ou « le chef » : le responsable actuel de la personne, ou celui qu'elle avait au moment de ce que vous mesurez.
Autre exemple
Une table de campagnes contenait les dépenses de toute l'entreprise, mais le chiffre d'affaires provenait d'un échantillon d'un achat sur cent. Les deux colonnes étaient étiquetées « pesos », et le retour sur investissement sortait négatif pour chaque campagne.
Que faire
Donnez à chaque variante un nom différent dans le code et à l'écran, même si c'est laid. Et avant de diviser ou de soustraire deux chiffres provenant de sources différentes, notez d'où vient chacun : si un résultat sort identique dans tous les cas (ils perdent tous, ils gagnent tous), soupçonnez l'échelle avant le métier.
Un mois qui n'est pas terminé paraît toujours moins bon qu'un mois clos. Ce n'est pas une tendance : c'est le calendrier.
Question détectrice
Ce calcul inclut-il une période qui n'est pas encore terminée ?
Signal d'alarme
« On voit déjà la tendance. »
Exemple et quoi faire
Exemple
La courbe des ventes « chute » au dernier point, qui correspond au mois qui n'est qu'à moitié écoulé.
Que faire
Arrêtez les indicateurs à la dernière période close, ou signalez la période partielle à l'écran. Et gardez les deux horloges séparées : les chiffres par groupe utilisent les mois clos ; les personnes nommément utilisent le jour en cours.
Un champ que la source écrase n'est pas un historique
Chiffres et données
Beaucoup de systèmes ne conservent que la valeur du jour. Si vous construisez une variable « historique » sur ce champ, vous mesurez le présent et le déguisez en passé.
Question détectrice
Ce champ garde-t-il sa valeur précédente quand il change, ou la remplace-t-il ?
Signal d'alarme
« La colonne est là, je vais simplement l'utiliser. »
Exemple et quoi faire
Exemple
Le système ne garde que le dernier responsable de chaque personne. Pour les personnes parties, ce responsable reste figé, si bien que « le taux de rotation de l'équipe de chaque responsable » finit par mesurer « cette équipe n'existe plus ».
Que faire
Demandez à la source si la donnée est un instantané ou un historique avant de l'utiliser pour regarder en arrière.
Un résultat parfait est un avertissement, pas une victoire
Chiffres et données
Si une seule variable sépare presque sans erreur les personnes parties de celles restées, elle contient très probablement le résultat lui-même.
Question détectrice
Ma mesure de qualité pourrait-elle monter parce que le modèle devine quand quelque chose s'est produit au lieu de deviner à qui c'est arrivé ?
Signal d'alarme
« C'est presque parfait ! » · « ajustons pour l'année et passons à autre chose. »
Exemple et quoi faire
Exemple
Un modèle devient soudain bien meilleur. Il s'avère qu'une variable vaut 1 pour toutes les personnes parties et 0 pour toutes celles restées, parce que la source la remplit différemment pour chaque groupe. Autre variante : le modèle apprend en quelle année quelque chose s'est produit, et non à qui cela est arrivé.
Que faire
Testez vers l'avant : entraînez sur le passé et évaluez sur une période ultérieure. Et avant d'ajuster pour un facteur, demandez-vous si ce facteur est justement ce qui décide du résultat que vous voulez prédire.
Si la règle qui définit « ce qui compte comme actif » est répétée dans chaque requête, les copies finiront par diverger. Ce n'est pas une question de si, mais de quand.
Question détectrice
Si je modifie cette définition, combien de fichiers dois-je toucher ? Si c'est plus d'un, la règle n'est pas configurée à un seul endroit.
Signal d'alarme
« Je le mets aussi ici, ce n'est qu'une ligne » · « ce nombre ne changera pas ».
Exemple et quoi faire
Exemple
Un validateur avait le nombre d'éléments de référence saisi à la main : 43. Quand le document est passé à 47, il a rejeté les quatre nouveaux comme inexistants. Maintenant, il compte les éléments du document lui-même.
Que faire
Placez la définition en un point que toutes les requêtes traversent, et faites-les toutes lire à partir de là. Un nombre saisi à la main qui recopie une valeur provenant d'ailleurs est aussi une définition répétée.
À ne pas confondre avec
Répéter une explication volontairement, dans un support pédagogique, n'est pas copier une définition. Ce qu'il ne faut pas copier, c'est la règle qui calcule la valeur.
Un processus déclare ce qu'il prévoit de faire, mais publie ce qu'il a réellement fait, et les deux ne concordent pas toujours. Celui qui consomme le résultat doit lire le résultat.
Question détectrice
Ceci est-il construit à partir de la configuration d'un processus ou de son résultat publié ?
Signal d'alarme
« La liste déclarée et le modèle, c'est la même chose. »
Exemple et quoi faire
Exemple
Un écran construisait ses contrôles à partir de la liste des variables que le modèle allait utiliser. L'entraînement en a écarté une, et pendant des jours un contrôle ne faisait rien.
Que faire
Dérivez-le du résultat publié. Et ce qui ne peut pas être dérivé doit échouer bruyamment au lieu de disparaître discrètement.
Quand vous modifiez une donnée que d'autres lisent par son nom, la liste de ceux qui la lisent doit être écrite. La mémoire en oublie toujours un.
Question détectrice
D'où vient la liste de ceux qui utilisent ceci : d'une recherche ou de ma mémoire ?
Signal d'alarme
« J'ai déjà couvert les trois endroits où c'est utilisé » · « ils l'ont déjà vu » · « j'ai déjà tout ajouté ».
Exemple et quoi faire
Exemple
Les libellés de trois écrans ont été mis à jour après le changement d'un modèle. Le quatrième, dont personne ne se souvenait, continuait de proposer les options de l'ancien modèle.
Autre exemple
En rédigeant un chapitre, on a affirmé de mémoire que le lecteur connaissait déjà trois fonctions d'un chapitre antérieur. Une recherche a montré que le chapitre n'en enseignait qu'une, et qu'un autre chapitre avait déjà expliqué le sujet présenté comme nouveau.
Encore un exemple
Une modification a été enregistrée avec la liste des fichiers écrite de mémoire, et l'un d'eux manquait : celui qui faisait fonctionner la nouveauté. La liste des changements en attente, relue ensuite, l'a montré.
Que faire
Tenez une carte écrite des impacts par type de modification. Parcourez-la en entier en disant « modifié » ou « sans objet parce que… », et si la modification crée un nouveau consommateur, ajoutez-le dans la même modification. Avant de citer une source, copiez la phrase que vous affirmez à partir de cette source : ce que quelqu'un dit qu'une autre personne a fait ou vu doit aussi être vérifié.
Un état vit dans plusieurs fiches : déplacez-les ensemble
Git et processus
Clôturer un élément en attente implique généralement trois endroits : la liste des éléments en attente, le test qui le surveille et le document qui le décrit. Si vous en déplacez un seul, les autres le contredisent.
Question détectrice
Quels autres endroits affirment cet état ? Nommez-les avant d'enregistrer.
Signal d'alarme
« Je mettrai à jour l'autre côté plus tard. »
Exemple et quoi faire
Exemple
Un élément en attente était marqué comme clos dans la liste, mais le test qui le surveillait était encore marqué « échec attendu » et le document le décrivait toujours comme ouvert. Trois endroits, trois versions.
Que faire
L'unité de travail est l'ensemble complet, dans la même modification.
Si votre produit a deux versions du même écran, pour deux types d'utilisateurs, deux régions ou deux produits, une amélioration de l'une est une amélioration en attente pour l'autre.
Question détectrice
Ce que je touche a-t-il un jumeau que les utilisateurs considèrent comme « le même module » ?
Signal d'alarme
« Ils ne me l'ont pas demandé pour l'autre. »
Exemple et quoi faire
Exemple
La version bureau a reçu un filtre par date. La version mobile, que les gens perçoivent comme « le même écran », en a été privée pendant un mois.
Que faire
Ne clôturez pas la modification tant que vous n'avez pas vérifié le jumeau et écrit soit « identique », soit « sans objet parce que… ».
Retirer un graphique ne retire pas l'affirmation qu'il faisait
Écriture et documentation
Si vous retirez quelque chose parce que la donnée n'était pas fiable, la même affirmation vit probablement encore dans d'autres textes, écrite avec d'autres mots.
Question détectrice
Quels autres textes disent la même chose que ce que je viens de retirer ?
Signal d'alarme
« J'ai déjà retiré le graphique. »
Exemple et quoi faire
Exemple
Un graphique peu fiable a été retiré, mais une carte « principales conclusions » et un plan d'action recommandaient encore ce que le graphique disait.
Autre exemple
Un plan de chapitres a été renuméroté de 7 à 15. Deux listes d'un autre document pointaient encore vers « 7.4 » et « 7.7 » de l'ancien plan, qui désignaient maintenant d'autres sujets. Quand vous remplacez un plan, les anciens numéros sont eux aussi des affirmations.
Que faire
Cherchez par sujet, pas par identifiant. Les échos n'ont pas de nom de variable.
Exécuter la requête ne prouve pas que le chiffre est juste
Chiffres et données
« Ça n'a pas échoué » n'est pas « c'est correct ». Comparez à quelque chose d'indépendant de votre propre calcul.
Question détectrice
Qu'est-ce qui, en dehors de mon propre code, va me permettre de vérifier ce résultat ? Et pour tout ce que le texte dit que le système fait, qu'il s'agisse d'un exemple, d'une règle ou de l'explication d'une option, l'ai-je exécuté sur le vrai moteur ?
Signal d'alarme
« Chez moi ça marche » · « ça n'a pas renvoyé d'erreur » · « c'est comme ça que ça marche, je viens de l'expliquer ».
Exemple et quoi faire
Exemple
Une question à choix multiples affirmait que comparer un nombre avec une chaîne de texte entre guillemets provoque une erreur. Dans certains autres moteurs, c'est le cas ; dans celui que les gens utilisaient réellement, la requête s'exécutait et renvoyait des lignes.
Autre exemple
Un texte expliquait correctement qu'un bloc nommé n'existe qu'à l'intérieur de sa propre requête, mais son propre exemple supposait que trois requêtes distinctes le partageaient. À l'exécution, la deuxième requête a provoqué une erreur : la table n'existait pas.
Encore un exemple
Chaque exemple d'une page a été exécuté, et trois phrases se sont tout de même révélées fausses : l'explication d'une option, écrite à la fin, décrivait ce que fait une ligne sans que personne ne l'ait jamais exécutée ; une règle de lecture des erreurs (« si elle dit ceci, alors il manque cela ») était contredite par une autre étape de la même page ; et l'introduction disait qu'une fonction « renvoie un résultat » alors qu'elle n'en renvoie pas.
Que faire
Recoupez avec un chiffre connu, le système source ou la période précédente. Testez dans l'environnement réel : avec ses autorisations, ses bibliothèques et la copie du code qui s'exécute réellement. Chaque affirmation sur le comportement du système est exécutée une fois avant d'être écrite, y compris celle qui apparaît au passage dans un exemple ou qui est écrite en dernier. Si l'affirmation est une règle générale (« seulement », « toujours », « jamais »), cherchez le cas qui la ferait échouer et exécutez-le aussi : « convertir en entier ne lit que les entiers » a été vérifié avec une chaîne de texte contenant des décimales, et s'est révélé faux pour un nombre à décimales. Quand vous énoncez une fraction (« cinq sur six »), nommez le tout dont elle est une fraction ; et un scénario inventé se vérifie lui aussi : la taille, l'écart et la p-value doivent être cohérents entre eux.
Un contrôle qui n'a jamais vu l'erreur ne vérifie rien
Tests et vérifications
Un test qui réussit toujours peut être cassé. La seule façon de le savoir est de le voir échouer face à la vraie erreur.
Question détectrice
Ai-je testé mon contrôle face à l'erreur dans les formes où elle apparaîtrait réellement ? Et face au cas correct ?
Signal d'alarme
« Il réussit déjà, donc il est bien configuré. »
Exemple et quoi faire
Exemple
Un test qui interdisait un mot ne cherchait que la version en minuscules ; avec une majuscule ou un accent, il réussissait.
Autre exemple
37 enregistrements en double avaient été insérés pour un exercice, et le décompte est revenu à 92 : les données contenaient déjà des correspondances naturelles. Une vérification qui comparait le décompte avec ce qui avait été inséré, avant l'enregistrement, l'a détecté.
Encore un exemple
Une règle qui détectait le code indenté signalait une ligne commençant par un texte : le cas qui devait passer n'avait pas cette forme. Et un test vérifiant que la comparaison de texte fonctionnait réussissait alors que la comparaison était cassée, parce qu'une autre relecture avait rejeté l'erreur en premier.
Que faire
Calibrez-le avec deux cas : un où il doit trouver quelque chose et un où il ne doit rien trouver, et lancez-le réellement le jour même de sa création. Le bon cas compte autant que le mauvais : un contrôle qui rejette ce qui est correct est lui aussi cassé, et c'est plus difficile à remarquer parce qu'il paraît strict. Le cas correct inclut les formes réelles de ce qui est juste, y compris celles que vous n'avez pas écrites vous-même : un autre ordre, un autre nom. Chaque contrôle se calibre lui-même : si un autre attrape l'erreur en premier, le vôtre n'a jamais été testé. Et une relecture qui répète ce qu'elle a déjà lu ne peut pas échouer (une « deuxième passe » qui relit le même fichier) : remplacez-la par une réconciliation qui échoue si quelque chose ne va pas.
La sonde ne passe pas par le canal qu'elle examine
Tests et vérifications
Si votre contrôle passe par le même circuit qui a pu causer le dommage, le dommage affecte aussi le contrôle, et il répond la même chose que tout soit juste ou faux.
Question détectrice
La transformation que j'examine transforme-t-elle aussi mon test ?
Signal d'alarme
« Je le vérifie en envoyant une autre requête exactement pareille. »
Exemple et quoi faire
Exemple
Ils cherchaient un problème d'accents en envoyant des requêtes avec des accents par le même chemin qui les abîmait.
Que faire
Construisez le test sous une forme que le dommage ne peut pas toucher.
Un test qui se désactive lui-même ne signale pas qu'il s'est désactivé
Tests et vérifications
Les branches qui disent « si je ne trouve pas les données, je saute le test » s'activent justement quand le monde change, et elles cessent de surveiller sans que personne ne le remarque.
Question détectrice
Mon test a-t-il une sortie silencieuse qui s'active lors d'un changement légitime ?
Signal d'alarme
« Si je ne trouve pas l'ancre, je saute le test. »
Exemple et quoi faire
Exemple
Un test repérait une table par son titre et, s'il ne la trouvait pas, il passait. Le titre a changé, et le test a réussi pendant des semaines sans rien vérifier.
Variante
Une vérification qui tombe au premier fichier cassé laisse sans surveillance chacun des fichiers suivants. Un validateur qui plante, au lieu de signaler « cette page ne peut pas être lue, ligne 12 », désactive toute la relecture.
Que faire
Si ce qui manque est un outil, le sauter est honnête. Si ce qui manque est la donnée surveillée, le test doit échouer. Et un fichier qui ne peut pas être lu est un constat avec sa ligne, et non la fin de la relecture.
Le filtre de votre contrôle exclut généralement exactement ce qui compte
Tests et vérifications
Chaque revue automatique filtre ce qui est « pertinent », et ce filtre peut la rendre aveugle précisément là où se trouve le problème.
Question détectrice
Que laisse de côté mon filtre ? Notez-le avant de croire le résultat.
Signal d'alarme
« Il a trouvé 48 différences, j'ai déjà la liste » · « le test passe par toutes ».
Exemple et quoi faire
Exemple
Un auditeur de design ne relisait que les éléments sans enfants. Les libellés qui demandaient une relecture contenaient une icône d'aide, donc il ne les voyait jamais.
Autre exemple
Un test parcourait chaque page en cochant toujours la première option et en exécutant chaque requête au fur et à mesure. Il réussissait toujours, sans jamais vérifier que la bonne réponse était acceptée.
Encore un exemple
Pour savoir si quelqu'un avait modifié un texte, les espaces étaient ignorés. Cela laissait de côté justement le cas de la page qui expliquait comment mettre en forme ce texte avec des espaces et des sauts de ligne. Normaliser, c'est aussi filtrer.
Que faire
Notez ce que le filtre laisse de côté et vérifiez à la main un échantillon des éléments exclus. Et quand vous découvrez qu'un filtre vous a rendu aveugle, cherchez les autres filtres semblables que vous avez déjà écrits : une revue qui retirait tous les espaces du code collait deux mots en un seul et rejetait du code correct, peu après que la même leçon avait été tirée d'une normalisation différente.
Du code qui compile n'est pas du code qui s'exécute
Tests et vérifications
Un vérificateur de syntaxe approuve du code qui plante à l'exécution. Un écran blanc avec tout « au vert » est la pire défaillance possible.
Question détectrice
Mon test : exécute-t-il le code ou se contente-t-il de le lire ?
Signal d'alarme
« La vérification de syntaxe passe, le code est bon. »
Exemple et quoi faire
Exemple
Une page a passé la vérification de syntaxe et la vérification de types. À l'ouverture, elle était blanche : elle utilisait une variable qui n'existe que sur le serveur.
Que faire
Ayez au moins un test qui fait tourner la page ou le programme en entier.
Vérifier la source n'est pas vérifier ce qui est livré
Tests et vérifications
Si vous vérifiez X et que l'utilisateur reçoit Y, dérivé de X, il existe entre les deux un code que personne ne regarde.
Question détectrice
Est-ce que quelqu'un vérifie ce qui atteint l'écran, ou seulement ce qui sort de la source ?
Signal d'alarme
« Ça vient de données déjà vérifiées » · « le fichier est bon ».
Exemple et quoi faire
Exemple
Ils ont vérifié que chaque résultat publié était correct, mais une version construite à partir de ces résultats est arrivée à l'écran : elle utilisait une règle différente pour les données manquantes.
Autre exemple
Un relecteur a lu le fichier source de chaque page et l'a approuvé. Un tableau qui se transformait en cartes sur mobile, et ne pouvait plus être comparé, n'est apparu que lorsque la page a été regardée.
Que faire
Vérifiez au point où cela atteint la personne : la page telle qu'elle est vue, le fichier qu'elle télécharge, le message qu'elle reçoit (voir aussi la leçon 41).
Une revue sur une seule dimension n'est pas une revue
Interface et design
« Ils sont déjà identiques » suppose d'avoir comparé chaque propriété visible, et non une seule.
Question détectrice
Ai-je comparé une propriété ou toutes celles que l'utilisateur voit ?
Signal d'alarme
« La taille correspond maintenant, donc le design est le même. »
Exemple et quoi faire
Exemple
Le design de deux écrans a été rendu identique en quatre tours : d'abord la taille, puis la typographie, puis les couleurs, puis la couleur des libellés. Chaque livraison disait « c'est fini ».
Autre exemple
Les illustrations d'un support ont été relues pour le contenu et la taille, mais pas pour le contraste : deux couleurs de texte se sont retrouvées sous le minimum lisible dans quatre images.
Que faire
Listez toutes les différences avant de corriger la première. Et dans vos notes, le verbe vous trahit : « c'est corrigé » et « ça devient » sont des intentions ; « ça dit » et « ça montre » sont des mesures.
Si vous repérez votre modification en cherchant un texte que l'utilisateur lit, comme un titre ou une étiquette, une autre amélioration se collera par-dessus et votre modification ne la retrouvera plus.
Question détectrice
Le texte que j'utilise comme ancre peut-il exister pour une autre raison, ou quelque chose peut-il grandir à l'intérieur ?
Signal d'alarme
« Je m'ancre sur le titre, il est unique. »
Exemple et quoi faire
Exemple
Une icône d'aide avait été ajoutée à côté de plusieurs titres, et les mises à jour qui se repéraient par ces titres ont cessé de fonctionner.
Autre exemple
Une relecture cherchait le texte « int( » pour vérifier qu'on avait converti un nombre, et il correspondait à l'intérieur de « print( » : toute ligne qui affichait quelque chose semblait passer. Ce que vous cherchez doit être un mot entier, pas un morceau d'un autre mot.
Encore un exemple
Une relecture prenait la dernière ligne imprimée par le code comme réponse. Avec une fonction qui affiche le nombre à l'intérieur sans le renvoyer, cette ligne existait pour une autre raison : la réponse apparaissait à l'écran, alors que le code ne la livrait jamais.
Que faire
Utilisez des marqueurs à vous, comme un identifiant ou un commentaire de section. Et quand une modification touche plusieurs blocs à la fois, vérifiez-les tous, pas seulement le premier.
La deuxième exécution est celle qui trouve le bogue
Scripts et fichiers
Une modification qui se répète sans rien casser doit être vérifiée en l'exécutant deux fois, et non une seule.
Question détectrice
Ai-je exécuté ma modification sur quelque chose qui l'avait déjà appliquée ? Quel autre processus touche ce même texte après moi ?
Signal d'alarme
« Ça a bien tourné, donc c'est fini. »
Exemple et quoi faire
Exemple
Pour vérifier qu'un script ne changeait rien à sa deuxième exécution, la somme de contrôle d'une même exécution a été comparée à elle-même, puis deux sommes prises à partir de listes de fichiers différentes. Les deux comparaisons disaient « identique » ou « différent » sans rien prouver. La comparaison qui fonctionne prend la somme, exécute le script et reprend la somme, à partir des mêmes fichiers et dans une seule commande.
Que faire
Exécutez-le deux fois à partir du même point de départ et comparez les fichiers : la deuxième exécution ne doit rien modifier.
Si vous insérez quelque chose avant « la cellule 9 », la cellule 9 est maintenant une autre cellule.
Question détectrice
Cet outil repère-t-il les éléments par leur position, et viens-je d'insérer ou de supprimer quelque chose avant ?
Signal d'alarme
« La cellule 9, c'est celle que je viens de regarder. »
Exemple et quoi faire
Exemple
Un script a inséré une cellule de titre avant la cellule 9 d'un carnet, puis a modifié « la cellule 9 » : il a modifié la cellule qu'il venait d'insérer.
Que faire
Repérez à nouveau l'emplacement après chaque insertion, et vérifiez le résultat en relisant la structure complète.
Ouvrir un fichier en écriture le vide instantanément. Si quelque chose échoue en plein milieu de l'écriture, vous vous retrouvez avec un fichier vide.
Question détectrice
Quelque chose peut-il échouer entre l'ouverture du fichier et la fin de l'écriture ?
Signal d'alarme
« C'est un simple remplacement, je l'écris directement. »
Exemple et quoi faire
Exemple
Un script a ouvert le fichier de configuration pour le réécrire, a échoué en calculant une des valeurs, et a laissé le fichier vide. Le serveur n'a jamais redémarré.
Que faire
Préparez tout en mémoire, écrivez dans un fichier temporaire et, à la fin, remplacez l'original en une seule étape.
Un réglage n'est pas un statut, et une alerte n'est pas une garantie
Scripts et fichiers
« La tâche planifiée est activée » ne veut pas dire « elle a tourné ce mois-ci ». Et attendre qu'une alerte vous prévienne en cas d'échec revient à faire confiance à l'alerte pour ne jamais échouer.
Question détectrice
Est-ce que je compte sur quelque chose qui « se déclenche tout seul » ?
Signal d'alarme
« C'est planifié, donc ça tourne. »
Exemple et quoi faire
Exemple
Une tâche planifiée apparaissait comme « active » mais n'avait pas tourné depuis deux mois, à cause d'un identifiant expiré. Le tableau de bord affichait le dernier point de données comme s'il datait d'aujourd'hui.
Que faire
Affichez à l'écran la date de la dernière mise à jour des données. Vérifiez quelles périodes manquent. Et faites en sorte que les processus puissent être relancés sans dupliquer les lignes.
Les filtres de qualité examinent généralement ce qui est nouveau. Ce qui est déjà en place n'est pas réexaminé, et ses hypothèses vieillissent sans que personne ne les remette en question.
Question détectrice
Cette chose qui tourne depuis des mois, quelqu'un a-t-il revérifié ses hypothèses depuis sa publication ?
Signal d'alarme
« On a déjà validé ça à la publication. »
Exemple et quoi faire
Exemple
Un rapport publié continuait à filtrer sur une colonne que la source avait cessé de remplir. Il affichait zéro, et comme il était « déjà validé », personne ne se posait la question.
Que faire
Soumettez ce qui est déjà en usage aux mêmes tests que le nouveau candidat, à chaque relecture.
Si un chiffre n'a pas changé alors qu'il aurait dû, ou a changé juste au moment où vous le regardiez, soupçonnez dans l'ordre : le cache, un autre processus qui écrit dans la même table, l'outil à travers lequel vous regardez, et seulement à la toute fin le système lui-même.
Question détectrice
Est-ce que je regarde le système, ou un cache, une copie, ou un outil qui a gardé un ancien instantané de celui-ci ou l'a modifié en cours de route ?
Signal d'alarme
« Je l'ai déjà corrigé et c'est toujours pareil » · « cette fois je l'ai vraiment bien tapé ».
Exemple et quoi faire
Exemple
Une table « avait perdu la moitié de ses colonnes ». Quelques minutes plus tard, elle était complète : vous la regardiez pendant qu'un autre processus la reconstruisait.
Autre exemple
Une nouvelle image « ne se chargeait pas » sur la page. Le fichier était bon : le serveur de test ne voyait pas les dossiers créés après son démarrage.
Encore un exemple
Un script « calculait mal un motif de texte ». Le script était bon : la console par laquelle on lui passait le code transformait chaque \n en un vrai saut de ligne avant que le script ne le lise. Et dans un carnet où les cellules partagent la mémoire, une erreur qui aurait dû apparaître n'est pas apparue : la variable était encore stockée depuis une cellule précédente.
Que faire
Prenez un second instantané quelques minutes plus tard avant de déclarer un désastre. Si un instrument vous a déjà trompé de la même façon, remplacez-le au lieu de continuer à le surveiller : un raté qui se répète n'est pas de la malchance, c'est le mauvais outil. Une console qui transforme \n ou \\ en cours de route ne convient pas pour lui passer du code : le code va dans un fichier, écrit avec un outil qui n'y touche pas, et s'exécute depuis là. Et tout ce qui est mécanique (une commande qui a déjà échoué trois fois) se bloque par un garde-fou, il ne se retient pas de mémoire.
Celui qui exécute et celui qui vérifie sont deux personnes différentes
Tests et vérifications
Si la même personne exécute et confirme, une erreur d'exécution se confirme elle-même.
Question détectrice
En dehors de la personne qui l'a fait, qui a relu le résultat tel que l'utilisateur le reçoit ?
Signal d'alarme
« Je l'ai déjà relu moi-même. »
Exemple et quoi faire
Exemple
Celui qui a écrit chaque page a aussi pris les captures d'écran de relecture, et seulement pour les étapes qu'il jugeait risquées. Le relecteur a lu le fichier source. Les étapes sans capture n'ont été vues par personne.
Que faire
L'un exécute et l'autre vérifie en lisant le résultat. « Je l'ai déjà fait » est le signe qu'on peut maintenant le vérifier, pas la vérification. Et celui qui vérifie ne doit pas regarder par le même canal que celui qui a fait (voir la leçon 14) : si les deux ne lisent que la source, aucun des deux ne voit l'écran.
Vérifier la commande avant de la transmettre à quelqu'un d'autre
Console et outils
Celui qui exécute la commande de quelqu'un d'autre le fait à l'aveugle. Chaque commande cassée érode la confiance qu'il aurait accordée à la suivante.
Question détectrice
Pour chaque nom de cette commande, l'ai-je lu aujourd'hui dans le système, ou l'ai-je tapé de mémoire ?
Signal d'alarme
« C'est la même commande que d'habitude. »
Exemple et quoi faire
Exemple
Une commande de déploiement contenait un nom de branche tapé de mémoire. La branche avait un autre nom, et celui qui l'a lancée a perdu une demi-heure avant de demander.
Que faire
Exécutez-la vous-même avant de la transmettre, et recopiez chaque nom (script, chemin, branche) depuis le système, pas depuis la mémoire.
Avancer vite dans la mauvaise direction n'est pas du progrès.
Question détectrice
Ce bloc est-il volumineux, difficile à annuler, ou modifie-t-il quelque chose qu'une autre personne a déjà décidé ? Si oui, expliquez et attendez. Sinon, dites ce que vous allez faire et allez-y : demander la permission à chaque étape a aussi un coût.
Signal d'alarme
« Je sais déjà ce qu'ils veulent. »
Exemple et quoi faire
Exemple
L'arborescence de dossiers d'un projet entier a été réorganisée sans prévenir. Le changement était correct en lui-même et a été entièrement annulé, parce qu'une autre personne avait déjà décidé de cette structure pour des raisons qui ne figuraient pas dans le code.
Que faire
Avant chaque grand bloc de travail, expliquez en langage simple ce que vous allez faire et pourquoi, et attendez la confirmation.
Rien de technique à l'écran, sauf si cela change une décision
Interface et design
Chaque élément d'un écran métier doit aider à décider quelque chose. Ce qui aide à l'audit va dans le code ; ce qui aide à décider va à l'écran, dans le langage métier.
Question détectrice
Cela modifie-t-il une décision de celui qui utilise l'écran ? Sinon, pourquoi est-ce là ?
Signal d'alarme
« Au cas où quelqu'un en aurait besoin. »
Exemple et quoi faire
Exemple
Un écran de ventes affichait, dans sa première ligne, l'identifiant interne de chaque commande et l'heure du dernier calcul. Personne ne décidait quoi que ce soit avec, et cela prenait la place des données qui comptaient.
Que faire
Avant d'ajouter quelque chose à l'écran, notez quelle décision cela change. Si cela n'en change aucune, ça va dans le journal technique ou dans le code, pas à l'écran.
Ce qui fonctionne mais ne se voit pas est signalé comme cassé
Interface et designwebapps
Si un bouton modifie quelque chose hors de la vue de l'utilisateur, fonctionner et ne pas fonctionner paraissent identiques.
Question détectrice
Juste après avoir utilisé le contrôle, sans bouger de là où il se trouve, l'utilisateur voit-il ce qui a changé ?
Signal d'alarme
« Ça marche, ça ne se voit simplement pas. »
Exemple et quoi faire
Exemple
Un filtre filtrait bien un tableau, mais le tableau se trouvait deux écrans plus bas. Les gens ont signalé qu'il « ne fait rien ».
Variante
Masquer un conteneur masque tout ce qu'il contient, même ce qui n'a rien à voir. Par exemple, un lien utile qui se trouvait à l'intérieur d'un contrôle retiré.
Que faire
Chaque contrôle dit ce qui a changé et amène l'utilisateur jusqu'à cet endroit. Et avant de masquer quelque chose, vérifiez quels autres éléments se trouvent à l'intérieur.
En petits caractères, « ÷ » et « + », « l » et « 1 », « O » et « 0 » se confondent. Si deux personnes lisent la même chose de travers, elles ne sont pas distraites : c'est la taille des caractères.
Question détectrice
À la taille et avec la police où il sera lu, ce symbole peut-il être confondu avec un autre, ou ressemble-t-il à quelque chose qu'on ne peut pas taper ?
Signal d'alarme
« Chez moi, ça a l'air bien. »
Exemple et quoi faire
Exemple
Deux personnes différentes ont lu « 98 ÷ 441 » comme « 98 + 441 » sur une carte en petits caractères, et toutes deux ont signalé que le calcul était faux.
Autre exemple
La police de code d'un support a fusionné >= en un seul symbole, ⩾. Celui qui apprend recopie ce qu'il voit, et ce symbole n'existe ni sur le clavier ni dans le langage.
Que faire
Quand un symbole se confond, remplacez-le par un mot : « 98 sur 441 » au lieu de « 98 ÷ 441 ».
Croire le symptôme d'un constat QA et mesurer la cause
Tests et vérifications
Un rapport QA a généralement raison sur le symptôme, mais propose une cause qui n'est qu'une hypothèse.
Question détectrice
Puis-je reproduire la cause avec ma propre mesure, ou l'accepter parce qu'elle semble juste ?
Signal d'alarme
« Le rapport dit déjà quelle est la cause. »
Exemple et quoi faire
Exemple
Un rapport demandait de corriger un graphique dont les totaux étaient faux, mais ce graphique n'existait pas à l'écran : les données transitaient sans rien pour les dessiner.
Que faire
Mesurez avant et après la correction. Une correction qui n'améliore qu'en partie le symptôme n'est pas encore close.
Une liste de choses à faire notée en passant devient périmée
Git et processus
Ce que vous avez noté comme « pour plus tard » en faisant autre chose n'existe peut-être plus, ou était peut-être une décision délibérée.
Question détectrice
Ai-je vérifié cet élément aujourd'hui, ou vais-je le traiter simplement parce qu'il est écrit ?
Signal d'alarme
« C'était sur la liste. »
Exemple et quoi faire
Exemple
Une note disait « retirer le filtre par date ». Quand on s'y est enfin mis, le filtre était déjà une décision écrite de l'équipe, et le retirer a cassé un rapport.
Que faire
Avant de traiter un élément en attente, vérifiez-le aujourd'hui et cherchez une décision écrite qui dit qu'il a été laissé ainsi volontairement.
Chaque chiffre d'un document provient d'une mesure datée et sourcée, et non de la mémoire ou d'une version antérieure du document.
Question détectrice
De quelles données et de quelle date viennent ce chiffre, ou cette comparaison (« plus d'un millier », « plus de la moitié », « presque tous ») ?
Signal d'alarme
« C'est le chiffre qu'on avait déjà » · « ça sort à peu près ça » · « on voit bien qu'ils passent tous ».
Exemple et quoi faire
Exemple
Une explication disait qu'un bogue faisait perdre « presque un ticket sur cinq ». Mesuré, c'était plus d'un sur cinq : la phrase venait d'un calcul mental, et non des données.
Autre exemple
Un texte affirmait qu'un groupe de cohortes « dépassait 50 % » ; cinq des douze étaient en dessous. Dans un autre, l'illustration montrait un calcul fait à la main qui ne tombait pas juste : le pourcentage multiplié par le total ne donnait pas le nombre dessiné.
Que faire
Avant d'écrire un chiffre, mesurez-le à nouveau et notez à côté quelles données et quelle date l'ont fourni. Les mots de quantité (« presque », « plus de », « la plupart ») sont des chiffres déguisés : mesurez-les de la même façon. Et si une image contient des calculs, faites en sorte que le même script qui la dessine fasse le calcul.
Documenter ce qui existe, pas ce que vous aimeriez qu'il existe
Écriture et documentation
Une relecture de documentation améliore le document ; elle ne redessine pas le système. Si le système a une limite, le document la dit. Il ne la cache pas et ne promet pas de la corriger.
Question détectrice
Ce que je m'apprête à écrire, décrit-il le fonctionnement actuel ou le fonctionnement souhaitable ?
Signal d'alarme
« Ça devrait marcher comme ça » · « ils vont le corriger ».
Exemple et quoi faire
Exemple
Un manuel disait que les données se synchronisaient toutes seules. Le système ne synchronisait que lorsque l'application était ouverte. La relecture a « corrigé » le manuel en promettant que ce serait bientôt automatique, au lieu d'énoncer la limite telle qu'elle était.
Que faire
Séparez les constats sur le document (« il est mal écrit ») des constats sur le système (« il fonctionne autrement que l'idéal »). Le second type se déclare comme une limitation.
Ce qu'on ne sait pas se marque, il ne s'invente pas
Écriture et documentation
Un document officiel affirme tout avec la même autorité. Un détail inventé, comme un responsable, un calendrier ou un délai de réponse, se lit exactement comme un détail réel.
Question détectrice
Est-ce que je connais ce détail, ou est-ce que je le suppose parce qu'il semble raisonnable ?
Signal d'alarme
« Forcément, c'est comme ça. »
Exemple et quoi faire
Exemple
Une procédure prévoyait un délai de réponse de 24 heures que personne n'avait convenu. Il avait été écrit parce qu'il semblait raisonnable, et une fois publié, il est devenu un engagement.
Que faire
Marquez ce qui manque de façon visible, par exemple « En attente » en rouge, et demandez à qui le sait. Une formulation neutre vaut mieux qu'une formulation fausse.
À ne pas confondre avec
La marque est destinée à la personne qui décide, pas au lecteur final. Un « confirmation en attente » dans un texte publié est une autre donnée qui ne devrait pas s'y trouver. Si le document sort avant d'être confirmé, utilisez une formulation neutre qui n'affirme pas ce qui manque, et gardez l'élément en attente dans le rapport ou le dossier du projet.
Chaque modification porte un nouveau numéro de version sur la couverture et une ligne dans l'historique, avec la date, ce qui a changé et qui l'a modifié. Quand deux exemplaires circulent, la version est la seule chose qui dit lequel est le bon.
Question détectrice
Si quelqu'un a la copie de la semaine dernière, comment sait-il qu'elle n'est plus la bonne ?
Signal d'alarme
« C'est une petite modification, elle n'a pas besoin de version. »
Exemple et quoi faire
Exemple
Deux exemplaires d'un manuel circulaient par e-mail. L'ancien disait que l'outil « s'ouvre par un double-clic », ce qui n'était plus vrai, et personne ne pouvait dire lequel des deux était le bon.
Que faire
Incrémentez le numéro de version et écrivez la ligne d'historique dans la même modification que celle du document.
Le journal dit ce qui reste et pourquoi, pas une chronique des erreurs
Git et processus
L'historique des modifications sert à comprendre le produit, pas à raconter les erreurs déjà résolues de celui qui a fait la modification.
Question détectrice
Cette ligne aide-t-elle à comprendre le produit ou à éviter de répéter une erreur, ou enregistre-t-elle simplement ce qui m'est arrivé ?
Signal d'alarme
« Gardons une trace de tout ce qui s'est passé. »
Exemple et quoi faire
Exemple
Un historique disait « A a été essayé et a échoué ; B a été essayé et a échoué ; C a été retenu ». Quelqu'un qui le lit des mois plus tard n'avait besoin que de C et de sa raison, et devait lire trois paragraphes pour le trouver.
Que faire
Écrivez l'état final et sa raison. Ce qui a été essayé et a échoué n'est noté que s'il enseigne quelque chose dont quelqu'un a besoin pour ne pas le refaire.
Vérifier dans le format que le lecteur voit réellement
Interface et designweb
Trouver un mot dans le texte ne prouve pas qu'il s'affiche. Le texte peut se trouver ailleurs dans le document pendant que le format censé l'afficher sort vide.
Question détectrice
Ai-je vu l'élément exact tel que le lecteur le voit, ou ai-je seulement trouvé le mot (ou le code) dans la source ?
Signal d'alarme
« Le mot est dans le fichier » · « c'est une correction d'une ligne ».
Exemple et quoi faire
Exemple
Trois étapes numérotées sont sorties sous forme de puces vides. La vérification automatique les a validées parce que ces mots apparaissaient ailleurs dans le document.
Autre exemple
Un avertissement « il y a d'autres colonnes à droite » avait été ajouté et considéré comme fait parce que le code était là. Il n'apparaissait jamais : un style de tableau général supprimait la condition qui l'activait. Quelqu'un d'autre l'a vu sur une capture d'écran.
Encore un exemple
Une option de réponse disait « Total : {2 * 78} » dans le fichier. Quand la page a été dessinée, le système a calculé ce qui se trouvait entre les accolades et a affiché « Total : 156 » : deux options identiques. Seule une personne qui a regardé l'écran l'a vu.
Variante
Les captures d'écran que juge un relecteur peuvent montrer un écran que personne n'atteint. L'outil de capture d'un cours répondait à chaque exercice de code par une ligne de remplissage juste pour passer à la suite, si bien que la capture « après » montrait cette ligne et un message « pas le résultat attendu » : les relecteurs ne voyaient jamais ce que voit l'apprenant après une bonne réponse. Sur ordinateur, les captures incluaient aussi l'en-tête et le menu latéral, et la leçon sortait en une bande illisible. Pour capturer en vue d'une relecture, répondez à chaque étape comme le ferait un utilisateur qui réussit, et ne capturez que la partie relue.
Que faire
Vérifiez l'élément exact, par exemple « ces trois étapes, en puces », et regardez la page comme le lecteur la verra au moins une fois. Une petite correction se vérifie aussi : c'est justement là qu'on attend le moins qu'une autre règle la remplace. Et la première fois que vous utilisez une nouvelle ressource sur la page (un bloc de code, un en-tête fixe), regardez-la aussi sur mobile.
Une relecture faite sur une ancienne copie fait réapparaître des erreurs déjà corrigées.
Question détectrice
La version que je modifie, est-ce la plus récente ou celle que j'avais ouverte ?
Signal d'alarme
« J'ai cette version ouverte depuis hier. »
Exemple et quoi faire
Exemple
Une réorganisation du manuel a été faite sur une version datant de plusieurs semaines. Elle redisait que l'outil « s'ouvre par un double-clic », ce qui n'était plus vrai.
Que faire
Prenez la structure proposée par la relecture et versez-y le contenu le plus récent, et non l'inverse.
Relire du début à la fin après de nombreuses corrections
Écriture et documentation
Après plusieurs séries de corrections ponctuelles, un document peut se contredire lui-même. Chaque correction était vraie dans sa propre section, mais personne n'a relu les autres.
Question détectrice
Combien de corrections ce document a-t-il reçues depuis la dernière fois que quelqu'un l'a relu en entier ?
Signal d'alarme
« J'ai vérifié chaque correction à son emplacement. »
Exemple et quoi faire
Exemple
Une section disait que rien n'est enregistré sans connexion. La FAQ affirmait encore que tout ce qui est capturé est conservé sur l'appareil.
Que faire
À la fin de chaque série, cherchez par sujet tout ce que le document dit sur ce que vous avez corrigé.
Ce que vous retirez de la sortie peut être le verdict
Console et outils
Ne regarder que les dernières lignes d'un résultat, ou le faire passer par une autre commande, peut jeter justement la partie qui disait « échec ». Une sortie tronquée d'un test raté ressemble exactement à celle d'un test réussi.
Question détectrice
Est-ce que je lis le verdict (combien ont réussi, combien ont échoué, comment cela s'est terminé), ou seulement un morceau de la sortie ?
Signal d'alarme
« Aucune erreur n'est apparue à l'écran » · « les dernières lignes suffisent ».
Exemple et quoi faire
Exemple
Une page a été marquée comme relue parce que son test « s'était terminé sans erreur ». Le résultat est passé par une commande qui n'affichait que la fin, et l'avis disant que le test avait échoué s'est perdu en chemin.
Autre exemple
Une suite de tests relançait automatiquement chaque test en échec. Les tests réussis au second essai ne comptaient pas comme échecs, seulement comme « instables », et la cause restait cachée : chaque changement d'étape demandait à nouveau la page au serveur. Sans relance, l'échec apparaissait et pouvait être mesuré.
Que faire
Trouvez la ligne du verdict avant de changer un statut. Si vous enchaînez des commandes, assurez-vous que l'échec de la première parvient jusqu'à la fin. Si la sortie n'a pas de verdict, cela signifie « je ne sais pas », pas « c'est passé » (voir la leçon 1). Et enregistrez la sortie complète dans un fichier et cherchez le verdict là : ainsi, vous n'avez pas à décider à l'avance combien lire.
Si vous ne testez que ce qui se passe quand tout va bien, celui qui fait une erreur trouve la faille. Et en apprentissage, faire des erreurs est ce qui arrive le plus souvent.
Question détectrice
Si l'utilisateur fait l'erreur la plus probable (une faute de frappe, une réponse vide, deux clics), que voit-il, et peut-il continuer ?
Signal d'alarme
« Ça marche avec la bonne réponse. »
Exemple et quoi faire
Exemple
Une cellule de requête ne comptait une tentative que lorsque la requête s'exécutait. Avec une faute de frappe, le bouton pour passer à l'étape suivante ne s'activait jamais, et la personne restait bloquée. Les tests réussissaient, parce qu'ils lançaient toujours la requête de départ, qui n'avait aucune erreur.
Que faire
Pour chaque contrôle, testez trois chemins : le bon, l'erreur la plus courante et le vide. Les trois disent ce qui s'est passé et laissent l'utilisateur continuer.
Ce qui s'exécute à chaque requête ne peut pas grandir avec le contenu
Interface et designweb
Quelque chose qui se fait à chaque page, comme lire tout le contenu ou recalculer un index, coûte peu avec dix pages et beaucoup avec cent. Cela grandit petit à petit et personne ne le remarque, jusqu'à ce que quelque chose commence à échouer « de temps en temps ».
Question détectrice
Cette chose qui s'exécute à chaque requête parcourt-elle tout le contenu ? Combien de temps prend-elle aujourd'hui, combien avec le double, et combien avec beaucoup de requêtes simultanées ?
Signal d'alarme
« Ça charge vite en local » · « c'est un échec intermittent ».
Exemple et quoi faire
Exemple
Chaque page d'un site lisait et analysait tout le contenu pour construire la table des matières. Seule, une page prenait 0,4 s. Mais la barre latérale demandait une quarantaine de pages à la fois, et ensemble elles prenaient 16 s. Des mois plus tard, les tests ont commencé à échouer lors du changement de page, et l'échec ressemblait à un problème du test.
Que faire
Mesurez sur le serveur compilé et selon la façon dont les gens l'utilisent, avec toutes ses requêtes ensemble, pas une page seule. Mettez en cache ce qui ne change pas pendant que le serveur tourne, et laissez un test qui mesure avec le cas qui l'a réellement rendu lent.
Ce qui est travaillé en parallèle entre en collision dans ce qui est partagé
Git et processus
Quand plusieurs personnes travaillent en même temps, chacune voit clairement sa propre partie. Ce qu'elles partagent (les tests, les données, les documents de tout le projet) combine leurs modifications : des noms qui se heurtent, des copies qui prennent du retard, des tests qui lisent le travail à moitié fini de quelqu'un d'autre. Intégrer est un travail, pas un copier-coller.
Question détectrice
Quel fichier deux parties touchent-elles en même temps, et qui l'intègre ? Mon test lit-il le travail à moitié fini de quelqu'un d'autre ?
Signal d'alarme
« Chacun a testé sa partie » · « l'échec est dans une autre partie ».
Exemple et quoi faire
Exemple
Quatre personnes écrivaient chacune une partie au même moment en laissant les parties communes comme livrable. À l'intégration, deux livrables utilisaient un nom qui existait déjà dans le test partagé, et le test a cessé de tourner. Un autre test gardait une copie de ce qu'il vérifiait ; la partie avait changé, pas la copie. Un test a échoué à cause d'une image qu'une autre personne dessinait encore. Et au final, chaque partie ne pouvait pas être enregistrée séparément : les fichiers partagés portaient déjà les modifications de tout le monde.
Que faire
Confiez à une seule personne l'intégration de ce qui est partagé, avec une étape qui s'arrête si un nom entre en conflit. Faites lire les tests à l'original, pas à une copie. Lancez toute la suite de tests une fois que tout le monde a fini, ou sans les parties qui changent encore, et dites lesquelles ont été exclues. Et enregistrez ensemble les parties qui partagent des fichiers, pour que chaque version enregistrée fonctionne en entier.
Si un fichier vient d'un générateur, la correction va dans le générateur
Scripts et fichiers
Quand un fichier est assemblé par un script ou à partir d'autres pièces, le fichier est une sortie, pas l'original. Tout ce qui est corrigé directement dedans est perdu à la prochaine génération, sans aucun avertissement.
Question détectrice
Ce fichier est-il écrit par autre chose (un script, un modèle, un assemblage de pièces) ? Si je le régénère, ma modification sera-t-elle toujours là ?
Signal d'alarme
« Je l'ai corrigé directement dans le fichier » · « je viens de le régénérer ».
Exemple et quoi faire
Exemple
Une note était assemblée à partir des sections remises par chacun. Trois lignes avaient été corrigées directement dans la note, et quand elle a été reconstruite à partir des contributions, les trois anciennes lignes sont revenues. Dans une autre pièce, un relecteur avait corrigé à la main le texte alternatif d'une page issue d'un modèle ; son auteur a régénéré la page, et la correction a disparu.
Que faire
Avant de corriger un fichier, découvrez d'où il vient. Corrigez la source (le modèle, le script, la contribution) et régénérez ; si vous devez corriger la sortie, corrigez aussi la source dans la même étape. Celui qui relit une sortie générée dit ce qui a changé pour que ce soit reporté dans la source. Et avant de reconstruire un fichier à partir de ses sources, comparez-le avec ce qui va en sortir : tout ce qui diffère est une correction qui serait perdue.
Une règle générale ne doit pas écraser en silence les règles spécifiques
Interface et designweb
Une règle qui s'applique à tout (un style global, une valeur par défaut) peut écraser ce que chaque élément a décidé pour lui-même, sans qu'aucun avertissement ne vous prévienne.
Question détectrice
Cette règle générale touche-t-elle à quelque chose que chaque élément décide déjà pour lui-même ? En cas de conflit, laquelle l'emporte ?
Signal d'alarme
« Je l'ai rendu global pour ne pas avoir à le répéter. »
Exemple et quoi faire
Exemple
Le style de focus clavier, écrit pour tout le site, venait avec son propre rayon de bordure. Comme il était placé au-dessus des styles propres à chaque composant, un bouton en forme de pilule changeait de forme au focus clavier. Personne ne l'a remarqué, parce qu'à la souris le focus n'apparaît pas.
Que faire
Laissez la règle générale ne toucher que ce qui lui appartient (le contour de focus, pas la forme). Si elle doit l'emporter volontairement, écrivez-le à côté. Et testez-la sur l'élément le plus différent, pas seulement sur le plus courant.
Si deux explications prédisent la même chose, votre exemple ne tranche pas entre elles
Chiffres et données
Un exemple ne confirme votre explication que si l'explication rivale donnerait un résultat différent. Si les deux prédisent la même chose, l'exemple vous laisse croire celle qui vous est venue en premier à l'esprit.
Question détectrice
Quelle autre explication donnerait ce même résultat ? Mon exemple l'écarte-t-il ?
Signal d'alarme
« Les chiffres le confirment. »
Exemple et quoi faire
Exemple
Une leçon comparait l'effet d'une hausse de cinq points sur la première étape d'un tunnel de conversion et sur sa dernière étape. La première l'emportait, et le texte disait : « elles valent plus là où il y a plus de visites ». Mais la première étape était aussi celle qui convertissait le moins, et c'était la vraie cause ; dans un tunnel où la première étape convertit mieux, c'est la dernière qui l'emporte, malgré moins de visites. Dans un autre projet, une page était accusée de mettre 2.7 s à se charger ; un test qui demandait les pages une à une passait même sans le correctif, parce que la vraie cause était quarante requêtes lancées en même temps.
Que faire
Avant d'enseigner ou de rapporter pourquoi quelque chose se produit, écrivez l'explication rivale et construisez un cas où les deux prédisent des résultats différents. Comparez des segments de même taille, essayez une autre taille d'exemple, et mesurez une affirmation générale sur des données simulées avant de l'écrire. Si vous ne pouvez pas les séparer, dites que l'exemple est compatible avec les deux.
Ce qui vous paraît évident est la première chose à enseigner
Écriture et documentation
Quelqu'un qui sait déjà ne voit pas les étapes qu'il franchit sans y penser. Son premier exemple apporte donc plusieurs notions nouvelles à la fois, et un débutant se perd dès la première ligne.
Question détectrice
Dans mon premier exemple, combien de notions sont nouvelles pour quelqu'un qui ne sait rien ? Chaque symbole, chaque mot, chaque nom de bouton et chaque action que je demande a-t-il déjà été enseigné ?
Signal d'alarme
« N'importe qui comprend ça » · « ce n'est qu'une ligne » · « c'est le mot habituel ».
Exemple et quoi faire
Exemple
Un cours de programmation pour débutants s'ouvrait sur une cellule qui introduisait six notions nouvelles à la fois, et le plan n'enseignait jamais ce qu'est un type de donnée, ni que = stocke et lit de droite à gauche. Le responsable du cours l'a formulé en une phrase : « vous supposez beaucoup de choses sur les apprenants ». Plus tard, trois leçons disaient « comme en faisant glisser une formule » ; aucune leçon n'avait enseigné le glisser-déposer, seulement « recopier la formule vers le bas ».
Que faire
Avant d'écrire, listez ce que votre exemple tient pour acquis (symboles, mots, clics, choses que l'apprenant aurait déjà dû construire) et enseignez-les d'abord : une idée nouvelle à la fois, chaque symbole expliqué à sa première apparition. Cherchez chaque mot qui correspond au nom d'un bouton, et chaque action demandée, de la même façon que vous cherchez un symbole. Si c'est possible, laissez une vérification automatique comparer ce que chaque exemple utilise avec ce qui a déjà été enseigné.
Écrire sur un outil qui évolue vite à partir de la pratique d'aujourd'hui, pas de mémoire
Écriture et documentation
Une leçon ou un guide sur un outil qui change tous les quelques mois devient périmé pendant qu'on l'écrit s'il repose sur ce que l'auteur se rappelle. Sa prémisse peut être fausse avant même que le premier lecteur la lise.
Question détectrice
Lesquelles des prémisses de ce texte dépendent de ce que l'outil sait faire aujourd'hui ? Quand les ai-je vérifiées pour la dernière fois, et d'après quelle source ?
Signal d'alarme
« C'est comme ça que ça marche » · « tout le monde fait comme ça ».
Exemple et quoi faire
Exemple
Un plan de module « analyse avec l'IA » commençait par « l'IA ne peut pas voir vos données, décrivez donc votre tableau au lieu de le coller ». Le responsable du cours a fait remarquer que les agents se connectent désormais à la base de données, exécutent eux-mêmes les requêtes et renvoient le chiffre. Une recherche avec sources et dates l'a confirmé : copier du code depuis un chat était la façon de faire deux ans plus tôt. Plusieurs leçons ont été réécrites autour de ce qui tient encore : définir la question, superviser l'agent et vérifier le chiffre.
Que faire
Avant d'écrire sur un outil qui évolue vite, cherchez la pratique actuelle avec des sources et des dates : ce que l'outil fait maintenant, ce qui est gratuit, ce que les gens utilisent réellement. Construisez le texte autour de la compétence qui survivra à la prochaine version (cadrer, superviser, vérifier), et gardez les étapes propres à l'outil à un seul endroit, facile à mettre à jour. Signalez ce que vous n'avez pas pu vérifier, et essayez vous-même avant de publier.
Le code passe par l'éditeur, pas par le traitement de texte du shell
Console et outils
Réécrire un fichier source avec les outils de chaînes du shell (le lire, remplacer, le réécrire) fait passer le code par des règles conçues pour autre chose : un encodage par défaut, la priorité des opérateurs, le guillemetage et l'échappement. La modification semble juste dans la commande, et le fichier qui en sort est différent de ce que la commande semble dire.
Question détectrice
Cette modification de code passe-t-elle par l'éditeur, ou par la lecture, le remplacement et l'écriture du shell, avec ses règles d'encodage, de priorité et de guillemets ?
Signal d'alarme
« C'est un simple remplacement, je le fais en une seule commande » · « plusieurs remplacements d'un coup, c'est plus rapide ».
Exemple et quoi faire
Exemple
Deux modifications dans une même session, toutes deux dans Windows PowerShell 5.1. Une lecture-remplacement-écriture d'un script (Get-Content, -replace, Set-Content -Encoding utf8) a lu le fichier dans la page de codes ANSI du système et l'a réécrit en UTF-8 : chaque ✓ et · est devenu ✓ et ·, et son auto-contrôle a affiché la marque déformée. Puis une liste de remplacements écrite comme `@('old', 'new' + "n" + 'more')` a perdu des lignes : dans PowerShell, la virgule lie plus fort que +`, donc chaque paire est devenue quatre éléments, et seul le premier morceau du nouveau texte a été écrit.
Que faire
Modifiez le code avec les outils d'édition et d'écriture de l'éditeur. Quand une modification doit être scriptée, écrivez le script dans un fichier et lancez-le avec un interpréteur qui lit et écrit en UTF-8 et dont les littéraux de chaînes sont simples (node fix.mjs, python -I fix.py). Puis regardez le diff : une modification qui a touché plus de lignes que prévu, ou des caractères que vous n'aviez pas touchés, vient du shell.
Si la réponse est la même sans la compétence, l'exercice ne la mesure pas
Tests et vérificationseducation
Un exercice ne vérifie une compétence que si quelqu'un qui saute cette compétence obtient un résultat différent. Si le point de départ, un exemple ou un raccourci produit déjà la bonne réponse, l'exercice valide tout le monde. C'est la leçon 13 appliquée aux exercices : un contrôle n'a de valeur qu'une fois que vous l'avez vu rejeter l'erreur.
Question détectrice
Quel résultat obtient quelqu'un qui saute exactement ce que j'enseigne, ou qui rend l'exercice sans y toucher ? Est-il différent du bon ? Ai-je choisi un cas où les deux calculs tombent juste par hasard (le premier groupe, la première étape, le total) ?
Signal d'alarme
« Avec la bonne réponse, il donne le chiffre, donc ça marche. »
Exemple et quoi faire
Exemple
Un exercice demandait le plus gros achat de l'été, avec un filtre de date. Le plus gros achat de toute la table était aussi un achat d'été : sans le filtre, le résultat était le même, et l'exercice l'a accepté. Un autre exercice exigeait que le code contienne un = ; il passait avec le résultat tapé à la main, total = 1945. Le contrôle regardait la lettre, pas la compétence.
Que faire
Résolvez chaque exercice trois fois : sans y toucher, avec l'erreur la plus probable, et correctement. Seule la troisième version doit passer. Puis appliquez la même liste de raccourcis à chaque exercice : le nombre tapé à la main, le code de départ avec la réponse ajoutée à la fin, le symptôme corrigé à la main au lieu de la cause, le mot exigé employé à vide, et une exécution avec la mémoire laissée par une tentative précédente. Gardez toute tolérance inférieure à l'écart entre la réponse et l'erreur la plus probable, et écrivez trois formes correctes qu'un apprenant utiliserait, pour que le contrôle ne rejette pas ce qui est juste.
Ce que l'apprenant voit avant de répondre ne peut pas contenir la réponse
Écriture et documentationeducation
Une question cesse de mesurer dès que sa réponse est déjà apparue : dans une image, dans l'idée clé, dans l'explication d'un autre exercice, dans le titre d'une étape ou dans une leçon précédente. Celui qui répond juste vient peut-être de la lire.
Question détectrice
L'apprenant voit-il ce chiffre, cette image ou cette formulation avant de répondre, ici ou dans une leçon précédente ? Pas seulement le nombre exact : aussi une approximation (« environ 25 »), la conclusion écrite dans une légende, un titre, un « vous venez de voir que… », ou ce que montre à l'écran la mauvaise réponse la plus probable d'un exercice précédent.
Signal d'alarme
« C'est juste du contexte » · « ce n'est que le titre » · « c'est la légende ».
Exemple et quoi faire
Exemple
Une illustration avec le bon chiffre était placée au-dessus de l'exercice qui le demandait. Une leçon demandait ce qui se passe quand on stocke une nouvelle valeur dans une variable, dans une étape intitulée « Stocker à nouveau la remplace ». Un résumé placé sous le quiz final était lu avant d'y répondre. Une boîte de retour qui apparaît après la première tentative, même ratée, donnait la direction de la réponse.
Que faire
Cherchez chaque réponse dans tout ce qui est montré avant sa question, y compris ce qui apparaît après une première tentative ratée, ce que le code de départ affiche à l'exécution, les fichiers téléchargeables et ce qui peut être compté dans un dessin. Rédigez en dernier le titre de l'étape et les objectifs d'apprentissage, et relisez-les à côté du résultat de chaque prédiction. Une vérification automatique trouve les chiffres exacts ; les approximations et les paraphrases ne sont repérées que par quelqu'un qui lit en ayant la réponse à l'esprit.
Une question à deux réponses défendables ne mesure rien
Écriture et documentationeducation
Si, avec ce que dit l'énoncé, une autre option peut aussi se défendre, celui qui choisit la « mauvaise » pour une bonne raison est pénalisé, et celui qui tombe juste a peut-être eu de la chance. La question mesure la phrase manquante, pas l'idée.
Question détectrice
Avec ce que dit l'énoncé et ce que la leçon a enseigné, puis-je défendre une autre option ? Quel fait faudrait-il pour l'écarter, et est-il écrit ?
Signal d'alarme
« Ça va de soi » · « évidemment, ça veut dire… ».
Exemple et quoi faire
Exemple
Une question demandait quoi faire d'une remise vide « quand la vente n'avait pas de remise ». La leçon avait enseigné qu'un vide qui est un fait reste vide, donc « la laisser telle quelle » était défendable ; la réponse attendue, le remplacer par zéro, dépendait de quelque chose que l'énoncé ne disait jamais : que le but était la moyenne sur toutes les ventes. Dans une autre, « la mesure principale est la part de clients qui paient le deuxième mois » ne disait pas la part de qui, et les deux lectures donnaient des résultats tantôt égaux, tantôt différents.
Que faire
Pour chaque mauvaise option, écrivez une ligne qui explique pourquoi elle est fausse, en utilisant seulement l'énoncé et la leçon. Si l'exclure demande un fait qui n'est pas écrit, ajoutez-le à l'énoncé : le but du calcul, la règle du système, le dénominateur d'une proportion, ce qu'on sait des données. Dans un exercice de tri, testez chaque élément dans chaque catégorie, et pas seulement dans la sienne.
Si l'on peut deviner la bonne option à sa place ou à sa longueur, le quiz mesure la devinette
Tests et vérificationseducation
Chaque question peut être correcte prise isolément, et l'ensemble donner quand même la réponse : la bonne option est toujours la deuxième, toujours la plus longue, ou toujours de taille moyenne. Les apprenants repèrent les régularités plus vite que les auteurs.
Question détectrice
Si je ne lis que la position et la longueur des options, sans le texte, est-ce que je devine la bonne plus d'une fois sur trois ?
Signal d'alarme
« J'ai vérifié chaque question, elles sont toutes correctes. »
Exemple et quoi faire
Exemple
Dans le quiz de clôture d'un module, la bonne réponse était la deuxième option dans six questions sur sept. Sur l'ensemble d'un cours, la bonne option était la plus longue dans 55 % des questions, alors que le hasard, avec trois options, donne une chance sur trois. Après un rééquilibrage de la longueur à la main, la bonne option s'est retrouvée la plus courte dans six questions sur sept d'une leçon, et celle du milieu dans chaque question de trois leçons de suite.
Que faire
Mélangez les options à l'affichage, selon un ordre qui ne dépend pas de l'endroit où la bonne a été écrite. Mesurez la plus longue, la plus courte et celle du milieu par fichier, et regroupez les petits fichiers par module, pour que quelques questions ne cachent pas la régularité. Relisez les chiffres au regard de ce que vous visiez : une passe d'équilibrage peut déplacer l'indice qui trahit la réponse au lieu de le supprimer.
Un indice pointe vers la cause de l'erreur, pas vers la réponse
Écriture et documentationeducation
Un indice apparaît après une mauvaise tentative. S'il donne la réponse, la ligne qui résout l'exercice, ou ce qui sépare la solution de l'erreur la plus probable, la deuxième tentative mesure la capacité à recopier.
Question détectrice
Quelqu'un qui lit cet indice pourrait-il réussir la tentative suivante sans la compétence ? Nomme-t-il la réponse, la ligne de solution, les étapes que l'exercice mesure, ou le nombre précédent auquel il doit correspondre ?
Signal d'alarme
« Ce n'est qu'un petit coup de pouce » · « ils ont déjà essayé une fois ».
Exemple et quoi faire
Exemple
La révision de 277 exercices vérifiés d'un cours a modifié 82 indices dans 49 fichiers. Certains donnaient la ligne qui résout l'exercice (« la deuxième est la… »). D'autres imposaient l'ordre qui sépare la solution de son erreur courante. Dans les exercices « vérifier par rapport à un résultat précédent », l'indice disait « cela doit correspondre à ce que vous avez obtenu dans la leçon 2.2 » : celui qui se souvenait du nombre précédent pouvait le taper sans faire l'étape.
Que faire
Rédigez l'indice sur la cause de l'erreur probable (« les positions commencent à 0, pas à 1 »), et ne citez que ce qui a déjà été enseigné. Gardez « cela doit correspondre au nombre précédent » pour l'explication affichée après la réponse, où l'on apprend que deux méthodes qui donnent le même nombre constituent une vérification. Relisez les indices au regard de l'erreur la plus probable de l'exercice, et non isolément.
Un stockage endommagé ne doit pas entraîner l'enregistrement suivant avec lui
Scripts et fichiersweb
Quelle que soit la façon dont un site enregistre ses données, une écriture endommagée peut aussi faire tomber ce qui vient après. Si les enregistrements sont ajoutés sous forme de lignes, une ligne coupée court colle l'enregistrement suivant à elle, et un lecteur qui saute les « lignes endommagées » perd les deux, sans rien signaler. Si tous les enregistrements sont dans un seul fichier, lu, modifié puis réécrit en entier, dès que ce fichier ne peut plus être lu, chaque nouvel enregistrement échoue, et seule une console que personne ne regarde le signale. C'est l'autre face de la leçon 24 : là, le fichier se vide ; ici, tout ce qui suit se perd.
Question détectrice
Si le stockage est endommagé demain, que devient l'enregistrement du prochain visiteur, et qui s'en aperçoit ?
Signal d'alarme
« Les lignes endommagées sont sautées » · « on ajoute juste à la fin » · « l'écriture est atomique, donc le fichier ne peut pas se casser ».
Exemple et quoi faire
Exemple
Dans les deux exécutions de la première simulation Web, le formulaire enregistrait chaque message sous forme de ligne JSON, et le panneau d'administration sautait toute ligne qu'il ne pouvait pas lire. Avec une ligne coupée à la fin du fichier, le message suivant a reçu la réponse « Merci ! », a été enregistré, et n'est jamais apparu dans le panneau d'administration. Une des deux versions avait un commentaire qui disait « ligne endommagée : ignorée ».
Autre exemple
Dans les deux exécutions de la relance, chaque message se trouvait dans un seul fichier JSON, écrit d'abord dans un fichier temporaire puis renommé, si bien qu'un plantage au milieu de l'écriture ne faisait plus de mal. Mais avec le fichier endommagé d'une autre façon (une modification à la main, un disque plein, une mauvaise restauration), chaque nouveau visiteur recevait « Erreur interne », la page d'administration n'affichait rien, et le seul signal était une trace d'erreur dans la console du serveur.
Que faire
Faites en sorte qu'un nouvel enregistrement ne dépende pas des anciens : ajoutez-le à un fichier qui se termine par un saut de ligne (commencez l'enregistrement par un saut de ligne s'il n'y en a pas), ou enregistrez chaque enregistrement dans son propre fichier, plutôt que de réécrire un seul fichier qui les contient tous. À la lecture, comptez ce qui n'a pas pu être lu et affichez ce compte là où le propriétaire le verra. Testez en endommageant le stockage à la main (coupez la dernière ligne, tronquez le fichier), puis en envoyant un enregistrement.
Un formulaire public reçoit des robots dès le premier jour
Interface et designweb
Un formulaire ouvert à Internet n'est pas rempli uniquement par des personnes. Si rien n'arrête les envois automatiques et si celui qui lit les messages ne peut pas faire le ménage, la première vague de spam enterre les vrais clients.
Question détectrice
Si demain mille faux messages arrivent, comment le responsable trouvera-t-il le seul vrai, et comment supprimera-t-il les autres ?
Signal d'alarme
« C'est un petit site, personne ne va l'attaquer » · « on ajoutera la limite plus tard ».
Exemple et quoi faire
Exemple
Dans les deux exécutions de la simulation Web, le formulaire de contact a accepté 650 messages envoyés par un script en quelques secondes, tous disant « merci ». L'administrateur n'avait ni pages ni bouton de suppression : la page d'administration atteignait entre un et six millions de pixels de haut, et sur mobile le texte du message sortait de l'écran. Dans les deux cas, le constructeur l'a noté comme en attente.
Que faire
Dès le départ, un frein peu coûteux : un champ caché que les gens ne remplissent pas, et une limite d'envois par adresse et par minute. Et une administration avec des pages, les plus récentes en premier, et un moyen de supprimer ou de marquer comme indésirable. Testez en envoyant des centaines de messages avec un script et en ouvrant l'administration sur un téléphone.
Un repli que personne n'a testé n'est pas un repli
Interface et designweb
Un formulaire avec method et action promet un repli qui fonctionne même si JavaScript échoue. Si le serveur ne répond qu'à ce que JavaScript attend, la promesse est fausse et la personne se retrouve face à du code.
Question détectrice
Si ce fichier JavaScript ne se charge pas, que voit la personne quand elle envoie le formulaire ?
Signal d'alarme
« Tout le monde a JavaScript de toute façon » · « je laisse l'action au cas où ».
Exemple et quoi faire
Exemple
Dans les deux exécutions de la simulation Web, le formulaire était envoyé avec JavaScript et déclarait method="post". Sans JavaScript, dans une version le serveur rejetait l'envoi avec une ligne de JSON et le message était perdu ; dans l'autre, il enregistrait le message et n'affichait que {"ok":true} sur une page blanche. Le résumé de cette seconde version disait qu'il n'enverrait pas sans JavaScript.
Que faire
Choisissez l'une des deux options et testez-la : soit le serveur accepte l'envoi normal et répond par une page (ou redirige vers une page de remerciement), soit le formulaire ne déclare pas de repli qu'il n'a pas. Envoyez une fois avec JavaScript désactivé.
Si vous désactivez le bouton, le focus part avec lui
Interface et designweb
Désactiver le bouton pendant l'envoi empêche un double envoi, mais le bouton perd le focus et le navigateur le place sur le document. Quelqu'un qui utilise le clavier, après l'avis, recommence depuis le début.
Question détectrice
Après l'envoi, qu'il ait réussi ou échoué, où se retrouve le focus et où va la touche Tab suivante ?
Signal d'alarme
« Je le désactive pour que personne n'envoie deux fois. »
Exemple et quoi faire
Exemple
Dans les deux exécutions de la simulation Web, l'envoi désactivait le bouton. Avec un e-mail rejeté par le serveur, l'avis apparaissait sous le bouton, le focus tombait sur le document, et la touche Tab suivante amenait l'utilisateur au premier lien de la page, loin du champ à corriger.
Que faire
Quand l'envoi se termine, placez le focus là où la personne doit continuer : sur le champ en erreur (marqué avec aria-invalid et son message à côté) ou sur l'avis de succès. Ou empêchez le double envoi sans désactiver, avec aria-disabled et un indicateur. Parcourez l'erreur en n'utilisant que le clavier.
Une connexion par mot de passe sans limite de tentatives n'est pas plus solide que le mot de passe le plus faible
Interface et designweb
Une connexion qui répond à chaque mauvais mot de passe à pleine vitesse permet à n'importe qui d'en essayer des milliers par minute. Un mot de passe par défaut solide masque le problème tant que le propriétaire n'en choisit pas un lui-même, et rien n'empêche que ce choix soit court.
Question détectrice
Combien de mauvais mots de passe peut-on essayer sur cette connexion en une minute, et que se passe-t-il après le cinquième ?
Signal d'alarme
« Le mot de passe par défaut est solide » · « ce n'est que la page d'administration ».
Exemple et quoi faire
Exemple
Dans les deux exécutions de la relance de la simulation Web, la page d'administration demandait un mot de passe et ne limitait jamais les échecs : 200 mauvais mots de passe d'affilée ont reçu 200 refus en moins d'une seconde, sans aucun blocage. Le mot de passe par défaut était long et aléatoire, mais le compte rendu de celui qui a construit le site indiquait au propriétaire comment en définir un nouveau, et rien n'exigeait qu'il soit long.
Que faire
Ralentissez ou bloquez les échecs répétés, par adresse et par compte, avec une attente qui s'allonge à chaque fois. Exigez une longueur minimale quand le propriétaire définit un mot de passe. Testez : envoyez vingt mauvais mots de passe d'affilée et vérifiez que les derniers sont refusés.
Aucune leçon ne correspond. Essayez moins de filtres.
Vous avez vu l'une de ces erreurs ? Partagez-la avec /ritual share.
Ritual