Comment créer un exemple minimal et reproductible ?

Quand vous posez une question sur des forums ou des groupes de discussion, les personnes pourront vous aider plus facilement si vous fournissez un code compréhensible et un moyen de reproduire le problème.

C'est ce que les gens appellent en anglais a minimal, reproducible example (reprex), a minimal, complete and verifiable example (mcve), ou encore a minimal, workable example (mwe).

Quel que soit le problème, il s'agit de s'assurer que votre code qui reproduit le problème suit les points suivants :

• Minimal : Utilisez le moins de code possible permettant de reproduire le problème
• Complete : Donner toutes les parties pour que quelqu'un d'autre puisse problème lui-même
• Reproducible : Testez le code que vous allez fournir pour vous assurer qu'il reproduit le problème

Le reste de cet article vous donnera juste des conseils sur comment rédiger un exemple minimal et reproductible.

Minimal

Plus il y a de codes à lire, moins les gens ont de chances de trouver votre problème. Simplifiez votre exemple de deux façons :

1. Repartez de zéro. Créez un nouveau code, en n'ajoutant que ce qui est nécessaire pour reproduire le problème. Utilisez des noms simples et descriptifs pour les fonctions et les variables, ne copiez pas les noms que vous utilisez dans votre code existant.
2. Diviser pour mieux régner. Si vous n'êtes pas sûr de la source du problème, commencez à supprimer le code petit à petit jusqu'à ce que le problème disparaisse, puis rajoutez la dernière partie.

Minimal and readable

Ne sacrifiez pas la clarté à la simplicité lorsque vous créez un exemple minimal. Utilisez une dénomination et une indentation cohérentes, et incluez des commentaires de code si nécessaire. Au besoin, utilisez le raccourci de votre IDE pour formater votre code. Utilisez également des espaces au lieu de tabulations. Suivant les endroits où vous allez mettre votre code, les tabulations risquent de ne pas être correctement formatées.

Complete

Assurez-vous que toutes les informations nécessaires pour reproduire le problème sont incluses dans la question elle-même :

• Si le problème nécessite un code côté serveur ainsi qu'une configuration, incluez le code pour les deux. Si le problème d'une page web nécessite du HTML, du JavaScript et du CSS, incluez ce code aussi. Le problème peut se trouver à un endroit dont n'y avez peut être pas pensé.
• Utilisez des blocs de code individuels pour chaque fichier ou extrait que vous incluez. Fournissez une description pour chaque bloc.
• Utilisez les Stack Snippets (JSFiddle, CodePen ou encore Plunker) pour inclure des fichiers HTML, JavaScript ou CSS exécutables.
• N'UTILISEZ PAS d'images de code. Copiez le code réel de votre IDE, collez-le dans la question, puis formatez-le en tant que code. Cela permet aux autres de lire et de tester plus facilement votre code. Un code en image est beaucoup plus difficile à copier/coller.

Reproducible

Pour vous aider à résoudre votre problème, d'autres devront vérifier son existence :

• Décrivez le problème. "Ça ne marche pas" n'est pas assez descriptif pour aider les gens à comprendre votre problème. Dites plutôt aux autres quel devrait être le comportement attendu. Dites aux autres quelle est la formulation exacte du message d'erreur, et quelle ligne de code le produit. Utilisez un résumé bref mais descriptif de votre problème comme titre de votre question.
• Éliminez les questions qui n'ont pas de rapport avec le problème. Si votre question ne concerne pas une erreur de compilation, assurez-vous qu'il n'y a pas d'erreurs de compilation. Utilisez un programme tel que JSLint pour valider. Validez aussi tout HTML ou XML.
• Vérifiez que votre exemple reproduit bien le problème ! Si vous avez corrigé le problème par inadvertance en écrivant l'exemple mais que vous ne l'avez pas testé à nouveau, il est intéressant de le savoir avant de demander de l'aide à quelqu'un d'autre.

Il peut être utile d'arrêter le système et de le redémarrer, ou de tester l'exemple dans un nouvel environnement pour confirmer qu'il fournit bien un exemple du problème.

Source

Pour plus d'informations sur la façon de déboguer votre programme afin de créer un exemple minimal, Eric Lippert a rédigé un article sur le sujet : How to debug small programs.

L'utilisation de "reprex" pour Reproductible Example a été inspirée par Jenny Bryan.

Cet article est une traduction d'un article rédigé en anglais sur Stack Overflow.