Comment poser de bonnes questions techniques – le guide ultime

Article original : How to Ask Good Technical Questions – the Ultimate Guide

Par Nabil Tharwat

Savoir poser des questions techniques efficaces est une compétence essentielle que tout ingénieur logiciel devrait maîtriser.

Vous pouvez être bloqué par un bug, incapable de comprendre pourquoi votre programme ne fonctionne pas correctement, ou avoir des difficultés à apprendre à implémenter un certain algorithme.

Dans toutes ces situations (et bien d'autres), vous irez probablement en ligne et poserez une question sur Stack Overflow, une communauté Discord, un subreddit, un groupe Facebook, ou même l'enverrez à un ami.

Ces conseils vous donneront les connaissances nécessaires pour rédiger des questions faciles à lire et à comprendre, et qui facilitent l'aide des autres.

Fournir un contexte pour votre question

La première chose sur laquelle vous devriez vous concentrer est le contexte. Le contexte aide les gens à mieux comprendre votre question, car ils sauront dans quelle situation vous vous trouvez et quels paramètres pourraient affecter leur réponse.

Les développeurs ne peuvent peut-être pas deviner quel langage de programmation vous utilisez ou quel framework vous pose problème. Ou ils ne comprennent peut-être pas votre configuration d'environnement simplement en lisant quelques exemples de code que vous avez fournis.

Ces détails contextuels font la différence si vous voulez que quelqu'un réponde à votre question, et de nombreux développeurs les négligent souvent malgré leur importance.

Par exemple, vous utilisez peut-être C++ 1999 et essayez d'utiliser une fonctionnalité disponible uniquement dans C++ 2011. Fournissez ce type de contexte, sinon les gens pourraient finir par regarder les mauvaises choses en essayant de vous aider.

Résumez votre question

Résumez votre question dans un titre. Comme sur Stack Overflow, chaque question doit avoir un titre qui transmet l'idée de base. Le titre doit être une synthèse relativement courte de la question en cours.

Le titre peut ne pas suffire à lister tous les détails. Mais vous devez au moins ajouter suffisamment de détails pour que, simplement en lisant le titre, quelqu'un puisse dire s'il peut vous aider avec ce problème ou non.

Cela est important car les gens n'ont généralement pas assez de temps pour lire toute la question (surtout si votre question détaillée fait plusieurs pages). Un titre percutant et utile est une synthèse respectueuse du temps qui fournit juste assez d'informations pour prendre une décision rapide.

Par exemple, dites plutôt "L'addition d'un float et d'un int en utilisant l'opérateur + évalue à int en C++11" au lieu de "Les opérateurs C++ ne fonctionnent pas". En faisant cela, vous fournissez suffisamment de contexte sur le problème et présentez le problème lui-même.

Créez un exemple minimal reproductible

Incluez toujours un exemple minimal reproductible si votre question dépend du code. Cela peut être un dépôt GitHub complet, un gist, ou même juste quelques lignes de code.

Vous ne voulez pas copier tout le projet ou tout le dépôt avec lequel vous travaillez, mais vous devez ajouter uniquement les éléments dont quelqu'un aurait besoin pour vous aider.

Si vous faites référence à un dépôt complet, assurez-vous de leur indiquer où regarder. Ensuite, indiquez clairement quels fichiers spécifiques sont concernés, quelles fonctions dans ces fichiers sont défectueuses, etc.

Cet exemple doit être complet, ce qui signifie qu'il est suffisant pour expliquer le problème et ne manque aucune importation, aucun module externe ou aucune fonction. Il contient tous les éléments dont quelqu'un a besoin pour pouvoir raisonner sur le code.

Il doit être minimal et ne contenir aucun élément de code non pertinent. Montrez uniquement le code qui affecte directement la réalisation de l'exemple et le problème en question.

Il doit également être reproductible. Je ne peux pas vous aider si je ne peux pas reproduire le problème auquel vous êtes confronté. Cela prend également en compte le contexte. Le manque de contexte suffisant avec des exemples rend plus difficile pour les gens de répondre à votre question.

Inclure toutes les restrictions et contraintes

Mentionnez toujours les restrictions et contraintes. Ne pas le faire conduit parfois à des réponses rejetées car la réponse dépasse une certaine contrainte que vous n'êtes pas autorisé à franchir.

Par exemple, vous pouvez résoudre une tâche pour l'école dans laquelle vous n'êtes pas autorisé à utiliser des structures de données complexes. Quelqu'un peut effectivement les utiliser en fournissant une réponse parce que vous n'avez pas listé ces contraintes.

Si vous oubliez de mentionner cela, vous perdrez le temps de quelqu'un et le vôtre également. C'est vraiment frustrant et peut amener les gens à ignorer complètement votre question. Mentionnez toujours les contraintes et restrictions.

Parfois, vous imposez par erreur des restrictions à vous-même, il est donc utile d'expliquer toujours pourquoi ces restrictions existent en premier lieu. Les gens pourraient vous surprendre !

Évitez d'utiliser des captures d'écran de code

Si vous publiez des captures d'écran de code avec votre question sur les réseaux sociaux, il est probable que ces images soient compressées. Elles deviendront difficiles à lire et pourraient finir par être complètement illisibles à cause de la quantité de code que vous avez entassée dans une seule image et de la compression de cette image.

Une image de mauvaise qualité comme celle-ci empêche les développeurs de copier votre code pour l'essayer eux-mêmes, les obligeant à écrire le code eux-mêmes juste pour commencer à vous aider.

Cela prend du temps et repoussera probablement ces développeurs à répondre à votre question – alors qu'ils auraient probablement été heureux de vous aider s'ils avaient pu lire le code dans ces captures d'écran en premier lieu.

De plus, gardez à l'esprit que les images ne sont pas aussi accessibles que le texte. Vous utilisez peut-être un thème pour votre IDE qui est difficile à lire pour certaines personnes. Soyez conscient de l'accessibilité de votre question pour la communauté.

Si vous devez ajouter des exemples de code, le texte est la meilleure façon de le faire. Le texte permettra aux lecteurs d'écran de lire votre question au lieu de dire quelque chose de générique comme "image". Il permettra également aux autres de lire le code dans le confort de leur propre thème de navigateur (pensez aux thèmes sombres et clairs de Stack Overflow).

Il existe de nombreuses façons de partager du code. De nombreuses solutions d'hébergement de code existent telles que Codepen, JSBin, GitHub Gist, Codesandbox et Pastebin.

Vous pouvez également simplement intégrer le code dans la question sous forme de texte. Cela est pris en charge nativement avec la coloration syntaxique sur des plateformes comme Stack Overflow et les forums de freeCodeCamp. Certaines communautés en ligne nécessitent des solutions spécifiques d'hébergement de code, et vous devez suivre ces exigences.

Partagez ce que vous avez déjà essayé

Listez ce que vous avez déjà essayé. Vous ne voulez pas paraître paresseux en posant une question. Votre dernière tentative peut être à un petit pas de résoudre le problème. Sans lister ce que vous avez essayé, les gens devront déboguer le problème dès le début.

Ne pas lister ce que vous avez essayé conduit souvent à des réponses rejetées également, car quelqu'un pourrait finir par suggérer quelque chose que vous avez déjà essayé. C'est frustrant et ce n'est pas seulement une perte de temps pour vous, mais aussi pour ceux qui essaient de vous aider.

Gardez vos données d'exemple petites

Souvent, nous avons besoin de données d'exemple pour tester le code que nous essayons d'exécuter. Cela peut être une réponse d'objet JSON avec des centaines de clés d'un serveur ou une table SQL avec des dizaines, voire des centaines de colonnes.

Dans ce cas, vous devez limiter la quantité d'informations que vous fournissez comme données d'exemple. Pourquoi inclure dix autres colonnes si le problème est lié à une seule d'entre elles ? Trop d'informations seront difficiles à manipuler.

Essayez de limiter la surface de votre code. Fournissez un objet JSON simplifié avec un nombre limité de clés ou une table SQL avec uniquement les colonnes liées au problème. Cela est plus facile à déboguer et plus facile à prendre en main.

Formatez, lintz et documentez votre code

Personne ne veut lire du code qui est tout sur la même ligne avec une mauvaise indentation, des incohérences dans la nomination des variables, ou un mauvais style en général. Suivez les conventions populaires si possible.

Les noms de variables et de fonctions doivent transmettre leur but. Les gens veulent pouvoir dire ce qu'une fonction fait simplement en lisant la signature. Ils ne veulent pas décrypter le code avant de le lire.

Si c'est complètement impossible de fournir des noms descriptifs, assurez-vous d'avoir une bonne documentation. Documentez ce que font les fonctions, à quoi servent les variables, et comment vous prévoyez de les utiliser.

Essayez d'utiliser un linter également. Les linters sont des outils qui parcourent votre code, l'inspectent et donnent des commentaires sur les améliorations possibles de la logique, les violations de style et de convention, et aident généralement à la lisibilité du code.

En général, vous ne voulez pas que votre code ressemble à ceci :

function someFunction ( p1,p2)
{
const b=p1+p2;
    console.log(b+p1*p2);
if( b > some_Const) throw 
            Error ( "something went wrong")
   else return 0;
}

mais plutôt à ceci :

function someFunction(p1, p2){
    const b = p1 + p2;

    console.log(b + p1 * p2);

    if(b > SOME_CONST) throw Error("Something went wrong");
    else return 0;
}

Ce genre de magie aide vraiment à lire le code et à déboguer le problème. Cela le rend plus facile à lire et à naviguer. Et vous devriez toujours formater votre code de toute façon, que vous le publiiez en ligne ou que vous travailliez dessus seul. Croyez-moi, cela aide.

De nombreux outils font cela, mais pour le développement web, les outils les plus populaires sont Prettier et ESLint. Ils supportent un certain nombre de langages et fonctionnent avec plusieurs éditeurs tels que Atom, Vim, VSCode, Visual Studio, et autres.

Presque tous les IDE sont livrés avec un formateur et un linter intégrés. Vérifiez l'IDE que vous utilisez pour ceux-ci avant de vous tourner vers des outils externes.

Vérifiez la grammaire de votre question

Parfois, les questions sont difficiles à déchiffrer car il y a trop d'erreurs grammaticales. Cela rend la question difficile à lire et limite le nombre de personnes qui peuvent vous aider.

Des plateformes comme Stack Overflow donnent aux éditeurs la possibilité d'améliorer les questions, mais vous ne devriez pas dépendre de cela. D'autres plateformes n'ont pas ce type de support, et il est donc généralement préférable de vérifier la grammaire de vos questions avant et après les publier.

Des outils comme Grammarly scannent automatiquement votre texte et conseillent sur l'amélioration de la grammaire ou corrigent même des erreurs grammaticales complètes. Il dispose d'extensions pour Firefox, Chrome, Safari et Edge. Essayez-le.

Suivez votre question

L'une des choses les plus frustrantes pour les personnes répondant aux questions en ligne est le manque de retour.

Une fois que vous posez une question et que vous obtenez une réponse, ne désertez pas tout. Ne fantômez pas les personnes qui essaient de vous aider. Fournissez un retour. Dites-leur ce qui a fonctionné, ce qui n'a pas fonctionné, et pourquoi.

Souvent, vous pouvez être laissé avec une solution partielle, mais sans retour, vous n'atteindrez jamais la solution complète.

Parfois, on vous demandera des informations supplémentaires. Vous avez peut-être oublié certains de ces conseils, ou vous n'avez peut-être pas fourni suffisamment d'informations. Accueillez les retours avec un sourire et rendez-les.

Et n'oubliez pas, les gens ne sont pas payés pour ces services. Ils paient avec leur temps et leurs efforts pour vous aider, alors appréciez cela et travaillez avec eux pour leur donner autant d'informations que possible. Cela portera ses fruits éventuellement.

Ajoutez un résumé

En général, essayez de garder vos questions courtes. Les longues questions prennent beaucoup de temps et sont souvent négligées pour cette raison. Je ne vais pas lire 3 pages d'une question avec la possibilité d'être abandonné ensuite.

En plus de résumer dans le titre, ajoutez un résumé au début de la question si elle est trop longue. Cela aidera les lecteurs en leur donnant une version courte de votre question au lieu de devoir lire tout le texte.

Cela leur permettra également de décider s'ils veulent continuer à lire tout le texte et s'ils pourront aider.

Nous sommes tous humains

Vous n'obtiendrez pas toujours des réponses joyeuses, accueillantes ou heureuses. Les gens ont des vies dans lesquelles ils peuvent être confrontés à des problèmes. Si vous poussez trop les gens, ils peuvent commencer à vous ignorer ou supprimer leurs réponses complètement. Respectez la vie privée des gens et donnez-leur de l'espace.

Si vous aimez cet article, n'oubliez pas de le partager ! Vous pouvez trouver plus de mon contenu sur mon blog. Merci pour la lecture !