Comment signaler des bugs efficacement

par Simon Tatham, programmeur professionnel et logiciel libre

Introduction

Toute personne ayant écrit un logiciel pour un usage public aura probablement reçu au moins un mauvais rapport de bogue. Des rapports qui ne disent rien (« ça ne marche pas! »); des rapports qui n’ont aucun sens; des rapports qui ne donnent pas assez d’informations; rapports qui donnent des informations erronées. Rapports de problèmes qui s’avèrent être une erreur de l’utilisateur; des rapports de problèmes qui s’avèrent être la faute du programme de quelqu’un d’autre; rapports de problèmes qui se révèlent être des défaillances du réseau.

Il y a une raison pour laquelle le support technique est considéré comme un travail horrible, et c’est la raison pour laquelle les rapports de bogues sont mauvais. Cependant, tous les rapports de bogues ne sont pas désagréables: je maintiens des logiciels libres lorsque je ne gagne pas ma vie, et parfois je reçois des rapports de bogues merveilleusement clairs, utiles et instructifs.

Dans cet essai, je vais essayer d’expliquer clairement ce qui fait un bon rapport de bogue. Idéalement, j’aimerais que tout le monde dans le monde lise cet essai avant de signaler tout bogue à qui que ce soit. Bien sûr, j’aimerais que tous ceux qui me signalent des bugs l’aient lu.

En résumé, l’objectif d’un rapport de bogue est de permettre au programmeur de voir le programme échouer devant lui. Vous pouvez soit leur montrer en personne, soit leur donner des instructions précises et détaillées pour l’échec. S’ils peuvent le faire échouer, ils essaieront de rassembler des informations supplémentaires jusqu’à ce qu’ils en connaissent la cause. S’ils ne peuvent pas le faire échouer, ils devront vous demander de rassembler ces informations pour eux.

Dans les rapports de bogues, essayez de préciser très clairement quels sont les faits réels (« J’étais à l’ordinateur et c’est ce qui s’est passé ») et quelles sont les spéculations (« Je pense que le problème pourrait être celui-ci »). Abandonnez les spéculations si vous le souhaitez, mais n’omettez pas les faits.

Lorsque vous signalez un bogue, vous le faites parce que vous voulez que le bogue soit corrigé. Inutile de jurer contre le programmeur ou d’être délibérément inutile: c’est peut-être leur faute et votre problème, et vous pourriez avoir raison d’être fâché contre eux, mais le bogue sera corrigé plus rapidement si vous les aidez en fournissant toutes les informations ils ont besoin. Rappelez-vous également que si le programme est gratuit, l’auteur le lui fournit par bonté. Par conséquent, si trop de gens sont grossiers avec eux, ils risquent de ne plus se sentir gentils.

« Ça ne marche pas. »

Attribuez au programmeur un crédit pour l’intelligence de base: si le programme ne fonctionnait pas du tout, il l’aurait probablement remarqué. Comme ils n’ont pas remarqué, ça doit marcher pour eux. Par conséquent, soit vous faites quelque chose de différent d’eux, soit votre environnement est différent du leur. Ils ont besoin d’informations. fournir cette information est le but d’un rapport de bogue. Plus d’informations sont presque toujours meilleures que moins.

De nombreux programmes, en particulier ceux gratuits, publient leur liste de bogues connus. Si vous pouvez trouver une liste de bogues connus, lisez-la pour voir si le bogue que vous venez de trouver est déjà connu ou non. Si cela est déjà connu, il ne vaut probablement pas la peine de le signaler à nouveau, mais si vous pensez avoir plus d’informations que le rapport dans la liste des bogues, vous pouvez quand même contacter le programmeur. Ils pourront peut-être résoudre le bogue plus facilement si vous pouvez leur donner des informations qu’ils ne possédaient pas déjà.

Cet essai est plein de directives. Aucune d’entre elles n’est une règle absolue. Les programmeurs ont des manières particulières d’aimer que les bugs soient rapportés. Si le programme est livré avec son propre ensemble de consignes de signalement d’erreurs, lisez-les. Si les directives fournies avec le programme sont en contradiction avec celles de cet essai, suivez celles qui sont fournies avec le programme!

Si vous ne signalez pas de bogue mais demandez simplement de l’aide pour utiliser le programme, vous devez indiquer où vous avez déjà cherché la réponse à votre question. (« J’ai regardé au chapitre 4 et à la section 5.2, mais je n’ai rien trouvé qui me dise si cela est possible. ») Le programmeur saura ainsi où les gens s’attendent à trouver la réponse, afin de faciliter l’utilisation de la documentation.

« Montre moi. »

L’un des meilleurs moyens de signaler un bogue est de le montrer au programmeur. Placez-les devant votre ordinateur, lancez leur logiciel et montrez ce qui ne va pas. Laissez-les regarder vous démarrez la machine, regardez vous exécuter le logiciel, regardez comment vous interagissez avec le logiciel et regardez ce que le logiciel fait en réponse à vos entrées.

Ils connaissent ce logiciel comme leur poche. Ils savent en quelles parties ils ont confiance et quelles parties sont susceptibles d’avoir des défauts. Ils savent intuitivement ce qu’il faut surveiller. Au moment où le logiciel fait quelque chose de manifestement faux, ils ont peut-être déjà remarqué quelque chose de faux précédemment qui pourrait leur donner un indice. Ils peuvent observer tout ce que fait l’ordinateur pendant le test et choisir eux-mêmes les bits importants.

Cela peut ne pas suffire. Ils peuvent décider qu’ils ont besoin de plus d’informations et vous demander de leur montrer à nouveau la même chose. Ils peuvent vous demander de leur expliquer la procédure afin de pouvoir reproduire le bogue eux-mêmes autant de fois qu’ils le souhaitent. Ils peuvent essayer de modifier la procédure plusieurs fois pour voir si le problème ne se produit que dans un cas ou dans une famille de cas connexes. Si vous êtes malchanceux, ils devront peut-être s’asseoir quelques heures avec un ensemble d’outils de développement et commencer réellement à enquêter. Mais le plus important est de laisser le programmeur regarder l’ordinateur quand il ne va pas. Une fois qu’ils peuvent voir le problème se produire, ils peuvent généralement le prendre à partir de là et commencer à essayer de le résoudre.

« Montre-moi comment me montrer. »

C’est l’ère de l’Internet. C’est l’ère de la communication mondiale. C’est à cette époque que je peux envoyer mon logiciel à quelqu’un en Russie en appuyant simplement sur un bouton, et il peut aussi m’envoyer des commentaires à ce sujet. Mais s’il a un problème avec mon programme, il ne peut pas me laisser rester devant lui pendant qu’il échoue. « Montre-moi », c’est bien quand tu peux, mais souvent tu ne peux pas.

Si vous devez signaler un bogue à un programmeur qui ne peut pas être présent en personne, le but de l’exercice est de leur permettre de reproduire le problème. Vous voulez que le programmeur exécute sa propre copie du programme, fasse les mêmes choses et le fasse échouer de la même manière. Quand ils peuvent voir le problème se présenter devant leurs yeux, ils peuvent alors le gérer.

Alors, dites-leur exactement ce que vous avez fait. S’il s’agit d’un programme graphique, indiquez-leur les boutons sur lesquels vous avez appuyé et leur ordre. Si c’est un programme que vous exécutez en tapant une commande, montrez-leur précisément quelle commande vous avez tapée. Dans la mesure du possible, vous devez fournir une transcription textuelle de la session, indiquant les commandes que vous avez saisies et les réponses fournies par l’ordinateur.

Donnez au programmeur toutes les informations auxquelles vous pouvez penser. Si le programme lit un fichier, vous devrez probablement envoyer une copie du fichier. Si le programme communique avec un autre ordinateur via un réseau, vous ne pourrez probablement pas envoyer de copie de cet ordinateur, mais vous pourrez au moins dire de quel type d’ordinateur il s’agit et (si vous le pouvez) quels logiciels sont exécutés.

« Ça marche pour moi. Alors qu’est-ce qui ne va pas? »

Si vous donnez au programmeur une longue liste d’entrées et d’actions, et qu’il lance sa propre copie du programme et que rien ne se passe mal, vous ne lui avez pas donné suffisamment d’informations. Peut-être que la faute n’apparaît pas sur tous les ordinateurs; votre système et le leur peuvent différer d’une certaine manière. Vous avez peut-être mal compris ce que le programme est censé faire et vous regardez tous les deux exactement le même écran, mais vous pensez que c’est faux et qu’ils savent que c’est juste.

Alors, décrivez aussi ce qui s’est passé. Dites-leur exactement ce que vous avez vu. Dites-leur pourquoi vous pensez que ce que vous avez vu est faux; Mieux encore, dites-leur exactement ce que vous espériez voir. Si vous dites « et que tout s’est mal passé », vous avez omis certaines informations très importantes.

Si vous voyez des messages d’erreur, dites au programmeur soigneusement et précisément ce qu’ils étaient. Ils sont importants! À ce stade, le programmeur n’essaie pas de résoudre le problème: il essaie simplement de le trouver. Ils ont besoin de savoir ce qui ne va pas et ces messages d’erreur sont les meilleurs efforts de l’ordinateur pour vous le dire. Notez les erreurs si vous n’avez pas d’autre moyen facile de les mémoriser, mais il est inutile de signaler que le programme a généré une erreur, à moins que vous ne puissiez également indiquer le type du message d’erreur.

En particulier, si le message d’erreur contient des chiffres, laissez le programmeur les avoir. Ce n’est pas parce qu’on ne voit aucune signification qu’il en soit. Les numéros contiennent toutes sortes d’informations pouvant être lues par les programmeurs et sont susceptibles de contenir des indices essentiels. Les chiffres dans les messages d’erreur sont présents, car l’ordinateur est trop confus pour signaler l’erreur en mots, mais fait de son mieux pour vous transmettre les informations importantes.

À ce stade, le programmeur effectue effectivement un travail de détective. Ils ne savent pas ce qui s’est passé et ne peuvent pas s’approcher suffisamment pour le voir se passer par eux-mêmes. Ils recherchent donc des indices susceptibles de le trahir. Les messages d’erreur, les chaînes de chiffres incompréhensibles et même les retards inexpliqués sont tout aussi importants que les empreintes digitales sur les lieux d’un crime. Garde les!

Si vous utilisez Unix, le programme peut avoir produit un vidage mémoire. Les dépotoirs sont une excellente source d’indices, ne les jetez pas. D’un autre côté, la plupart des programmeurs n’aiment pas recevoir d’énormes fichiers de base par courrier électronique sans avertissement, alors renseignez-vous avant d’en envoyer un à qui que ce soit. Sachez également que le fichier principal contient un enregistrement de l’état complet du programme: tous les « secrets » impliqués (le programme traitait peut-être un message personnel ou traitait des données confidentielles) peuvent être contenus dans le fichier principal.

« Alors j’ai essayé … »

Il y a beaucoup de choses que vous pouvez faire quand une erreur ou un bogue survient. Beaucoup d’entre eux aggravent le problème. Une de mes amies à l’école a effacé par erreur tous ses documents Word. Avant de faire appel à un expert, elle a essayé de réinstaller Word, puis elle a essayé de lancer Defrag. Aucune de celles-ci n’a aidé à récupérer ses fichiers et, entre elles, elles ont brouillé son disque au point qu’aucun programme Undelete au monde n’aurait été capable de récupérer quoi que ce soit. Si elle l’avait laissée seule, elle aurait peut-être eu une chance.

Les utilisateurs comme celui-ci sont comme une mangouste attachée dans un coin: dos au mur et voyant la mort le regarder au visage, il attaque avec frénésie, car faire quelque chose doit être mieux que ne rien faire. Ce n’est pas bien adapté au type de problèmes que produisent les ordinateurs.

Au lieu d’être une mangouste, soyez une antilope. Lorsqu’une antilope est confrontée à quelque chose d’inattendu ou d’effrayant, elle se fige. Il reste absolument immobile et essaie de ne pas attirer l’attention, pendant qu’il s’arrête, réfléchit et définit la meilleure chose à faire. (Si les antilopes disposaient d’une ligne d’assistance technique, elles téléphonaient à ce moment-là.) Ensuite, une fois que la décision la plus sûre est prise, c’est le cas.

Lorsque quelque chose ne va pas, arrêtez immédiatement de faire quoi que ce soit. Ne touchez aucun bouton du tout. Regardez l’écran et remarquez tout ce qui sort de l’ordinaire et souvenez-vous-en ou écrivez-le. Ensuite, commencez peut-être avec précaution à appuyer sur « OK » ou « Annuler », selon ce qui vous semble le plus sûr. Essayez de développer une réaction réflexe – si un ordinateur fait quelque chose d’inattendu, gèlez-le.

Si vous parvenez à vous sortir du problème, que ce soit en fermant le programme concerné ou en redémarrant l’ordinateur, il est bon d’essayer de le rétablir. Les programmeurs aiment les problèmes qu’ils peuvent reproduire plus d’une fois. Les programmeurs heureux corrigent les bogues plus rapidement et plus efficacement.

« Je pense que la modulation tachyon doit être polarisée à tort. »

Ce ne sont pas seulement les non-programmeurs qui produisent des rapports de bugs erronés. Certains des pires rapports de bugs que j’ai jamais vus viennent de programmeurs, et même de bons programmeurs.

J’ai déjà travaillé avec un autre programmeur, qui n’arrêtait pas de trouver des bogues dans son propre code et essayait de les corriger. De temps en temps, il rencontrait un insecte qu’il ne pouvait pas résoudre et il m’appelait pour vous aider. « Qu’est-ce qui ne va pas? » Je demanderais. Il répondait en me disant son opinion actuelle sur ce qui devait être corrigé.

Cela a bien fonctionné quand son opinion actuelle était juste. Cela signifiait qu’il avait déjà effectué la moitié du travail et que nous pouvions terminer le travail ensemble. C’était efficace et utile.

Mais très souvent il s’était trompé. Nous avons travaillé pendant un certain temps pour essayer de comprendre pourquoi une partie du programme produisait des données incorrectes, et nous découvririons finalement que ce n’était pas le cas, que nous examinions un code parfaitement bon depuis une demi-heure. et que le problème réel était ailleurs.

Je suis sûr qu’il ne ferait pas ça à un médecin. « Docteur, j’ai besoin d’une ordonnance pour Hydroyoyodyne. » Les gens savent que cela ne doit pas être dit à un médecin: vous décrivez les symptômes, les inconforts, les douleurs, les éruptions cutanées et les fièvres, et vous laissez le médecin établir le diagnostic du problème et des mesures à prendre. Sinon, le médecin vous exclut comme un hypocondriaque ou un crackpot, et à juste titre.

C’est la même chose avec les programmeurs. Fournir votre propre diagnostic peut parfois être utile, mais indiquez toujours les symptômes. Le diagnostic est une option supplémentaire, et non une alternative à donner les symptômes. De même, l’envoi d’une modification du code pour résoudre le problème est un ajout utile à un rapport de bogue, mais ne peut en remplacer un.

Si un programmeur vous demande des informations supplémentaires, ne les inventez pas! Quelqu’un m’a signalé un bug une fois et je lui ai demandé d’essayer une commande qui, je le savais, ne fonctionnerait pas. La raison pour laquelle je lui ai demandé de l’essayer était que je voulais savoir lequel des deux messages d’erreur différents cela donnerait. Savoir quel message d’erreur est revenu donnerait un indice essentiel. Mais il ne l’a pas réellement essayé – il m’a juste envoyé un mail pour me dire « Non, ça ne marchera pas ». Il m’a fallu du temps pour le convaincre de l’essayer.

Utiliser votre intelligence pour aider le programmeur va bien. Même si vos déductions sont fausses, le programmeur devrait vous être reconnaissant d’avoir au moins essayé de leur faciliter la vie. Mais signalez également les symptômes, sinon vous risquez de rendre leur vie beaucoup plus difficile.

« C’est drôle, ça a été fait il y a un moment. »

Dites « faute intermittente » à n’importe quel programmeur et regardez son visage s’effondrer. Les problèmes simples sont ceux où l’exécution d’une simple séquence d’actions entraînera l’échec. Le programmeur peut ensuite répéter ces actions dans des conditions de test étroitement surveillées et observer ce qui se passe de manière très détaillée. Trop de problèmes ne fonctionnent tout simplement pas de cette façon: certains programmes échoueront une fois par semaine, ou encore une fois dans une lune bleue, ou n’échoueront jamais lorsque vous les testerez devant le programmeur, mais échoueront toujours lorsque le délai sera proche up.

La plupart des défauts intermittents ne sont pas vraiment intermittents. La plupart d’entre eux ont une certaine logique quelque part. Certaines peuvent se produire lorsque la machine manque de mémoire, d’autres lorsqu’un autre programme tente de modifier un fichier critique au mauvais moment, et d’autres uniquement dans la première moitié de l’heure! (J’ai effectivement vu un de ceux-ci.)

En outre, si vous pouvez reproduire le bogue mais que le programmeur ne le peut pas, il est fort possible que leur ordinateur et votre ordinateur soient différents d’une manière ou d’une autre et que cette différence soit à l’origine du problème. Un jour, j’ai eu un programme dont la fenêtre s’est enroulée en une petite boule dans le coin supérieur gauche de l’écran. Elle s’est assise là et a boudé. Mais il ne l’a fait que sur 800×600 écrans; c’était bien sur mon moniteur 1024×768.

Le programmeur voudra tout savoir sur le problème. Essayez sur une autre machine, peut-être. Essayez-le deux ou trois fois et voyez combien de fois il échoue. Si cela ne fonctionne pas lorsque vous faites un travail sérieux, mais pas lorsque vous essayez de le démontrer, cela peut être une longue durée de fonctionnement ou des fichiers volumineux qui le font tomber. Essayez de vous rappeler le plus de détails possible sur ce que vous avez fait quand il est tombé, et si vous voyez des tendances, mentionnez-les. Tout ce que vous pouvez fournir doit être une aide. Même si ce n’est que probabiliste (comme « cela a tendance à planter plus souvent quand Emacs est en cours d’exécution »), cela pourrait ne pas fournir d’indices directs sur la cause du problème, mais aider le programmeur à le reproduire.

Plus important encore, le programmeur voudra savoir avec certitude s’il s’agit d’un véritable défaut intermittent ou d’un défaut spécifique à la machine. Ils voudront connaître beaucoup de détails sur votre ordinateur afin de savoir en quoi il diffère du leur. Beaucoup de ces détails dépendent du programme, mais vous devez absolument être prêt à fournir les numéros de version. Le numéro de version du programme lui-même et le numéro de version du système d’exploitation, et probablement les numéros de version de tout autre programme impliqué dans le problème.

« Alors j’ai chargé le disque sur mon Windows … »

Écrire clairement est essentiel dans un rapport de bogue. Si le programmeur ne peut pas dire ce que vous vouliez dire, vous pourriez aussi bien ne rien dire.

Je reçois des rapports de bogues du monde entier. Beaucoup d’entre eux ne parlent pas anglais, et beaucoup s’excusent pour leur anglais médiocre. En général, les rapports de bogues avec des excuses pour leur anglais médiocre sont en réalité très clairs et utiles. Tous les rapports les moins clairs proviennent d’anglophones anglais qui pensent que je les comprendrai même s’ils ne font aucun effort pour être clairs ou précis.

– Être spécifique. Si vous pouvez faire la même chose de deux manières différentes, indiquez laquelle vous avez utilisée. « J’ai sélectionné Charger » pourrait signifier « J’ai cliqué sur Charger » ou « J’ai appuyé sur Alt-L ». Dis ce que tu as fait. Parfois ça compte.
– Soyez prolixe. Donner plus d’informations plutôt que moins. Si vous en dites trop, le programmeur peut en ignorer une partie. Si vous en dites trop peu, ils doivent revenir et poser plus de questions. Un rapport de bogue que j’ai reçu était une seule phrase; chaque fois que je demandais plus d’informations, le journaliste répondait par une autre phrase. Il m’a fallu plusieurs semaines pour obtenir une quantité utile d’informations, car les phrases se résumaient en phrases courtes.
– Faites attention aux pronoms. N’utilisez pas de mots tels que « it », ou de références telles que « la fenêtre », lorsque leur signification n’est pas claire. Considérez ceci: « J’ai lancé FooApp. Il a affiché une fenêtre d’avertissement. J’ai essayé de le fermer et il s’est écrasé. » Ce que l’utilisateur a essayé de fermer n’est pas clair. Ont-ils essayé de fermer la fenêtre d’avertissement, ou l’ensemble de FooApp? Cela fait une différence. Au lieu de cela, vous pouvez dire « J’ai lancé FooApp, qui a ouvert une fenêtre d’avertissement. J’ai essayé de fermer la fenêtre d’avertissement et FooApp est tombé en panne. » C’est plus long et plus répétitif, mais aussi plus clair et moins facile à mal comprendre.
– Lis ce que tu as écrit. Lisez le rapport pour vous et voyez si vous pensez que c’est clair. Si vous avez répertorié une séquence d’actions susceptibles de provoquer l’échec, essayez de les suivre vous-même pour voir si vous avez manqué une étape.

Résumé

– Le but premier d’un rapport de bogue est de laisser le programmeur voir l’échec de ses propres yeux. Si vous ne pouvez pas être avec eux pour le faire échouer devant eux, donnez-leur des instructions détaillées afin qu’ils puissent le faire eux-mêmes.
– Si le premier objectif n’aboutit pas et que le programmeur ne peut pas le voir échouer, le deuxième objectif d’un rapport de bogue est de décrire ce qui s’est mal passé. Décrivez tout en détail. Indiquez ce que vous avez vu et indiquez également ce que vous espériez voir. Notez les messages d’erreur, surtout s’ils ont des chiffres.
– Lorsque votre ordinateur fait quelque chose d’inattendu, gelez. Ne faites rien tant que vous n’êtes pas calme et ne faites rien qui puisse, selon vous, être dangereux.
– Essayez certainement de diagnostiquer vous-même la faute si vous pensez pouvoir le faire, mais si vous le faites, vous devez tout de même signaler les symptômes.
– Soyez prêt à fournir des informations supplémentaires si le programmeur en a besoin. S’ils n’en avaient pas besoin, ils ne le demanderaient pas. Ils ne sont pas délibérément maladroits. Ayez à portée de main les numéros de version, car ils seront probablement nécessaires.
– Écrire clairement. Dites ce que vous voulez dire et assurez-vous qu’il ne peut pas être mal interprété.
– Surtout, soyez précis. Les programmeurs aiment la précision.
______________________________________________________
Disclaimer: Je n’ai jamais vu de mangouste ni d’antilope. Ma zoologie peut être inexacte.

Page source: https://www.chiark.greenend.org.uk/~sgtatham/bugs.html


Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *