Rédige les commentaires d'analyseur

Ce document fournit des informations et des consignes sur la façon d'écrire les commentaires produits par l'analyseur.

Contenu

Le contenu des commentaires d'analyseur est stocké sous forme de document Markdown dans le dépôt exercism/website-copy. Les commentaires contiennent une chaîne de pointeur, au format <track-slug>.<exercise-slug>.<comment-slug>, qui pointe vers un document Markdown spécifique dans le dépôt website-copy.

Par exemple, ruby.two-fer.string-interpolation fait référence à https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md.

Formulation

• Évite les commentaires inutilement verbeux. Sois concis.
• Reste neutre et observationnel ; évite les déclarations chargées et les généralisations.
• Formule la recommandation de manière explicite.
• Quand c'est possible, place la recommandation en premier, puis l'explication.
• Évite « me », « I », « we », etc., car le bot n'est pas une personne.
• Évite « you » et « your code », car cela peut parfois donner l'impression de juger la personne plutôt que le code.
• Évite des mots comme « just », « simply », « obviously », qui peuvent passer pour condescendants : si le commentaire est nécessaire, ce n'était manifestement pas évident.
• Évite de supposer ce que les gens savent ou ne savent pas. La seule exception concerne les connaissances issues d'exercices core déjà terminés. Évite « as you know », « as you remember », « as you learned », « now that we all understand x », car même si quelque chose a été dit, la personne ne l'a pas forcément compris.

Conseils

• Vise l'aisance, pas la compétence : l'objectif d'un parcours de langage sur Exercism est de donner aux gens un moyen d'atteindre un haut niveau d'aisance avec un faible niveau de compétence. On vise l'aisance dans la syntaxe, les idiomes et la bibliothèque standard du langage.
• Suggère du code idiomatique quand c'est possible, où idiomatique désigne le code que la quasi-totalité des développeurs (non amateurs) qui écrivent dans ce langage écriraient. Si une suggestion non idiomatique est faite, mentionne-le et explique pourquoi la suggestion peut quand même être utile.
• Nomme la différence entre ce que la personne fait et ce qui est « idiomatique » dans le langage.
• Utilise les termes appropriés et la nomenclature, pour que les gens puissent reconnaître ces concepts ailleurs et puissent aussi les rechercher par eux-mêmes.
• Ne donne pas la solution comme conseil général pour tout le mentorat sur Exercism. L'apprentissage s'ancre quand on découvre la réponse par soi-même. C'est une expérience extrêmement grisante, et le coup émotionnel la rend mémorable. Cependant, si la découverte ne déclenche pas une dose de dopamine, il est tout à fait logique de montrer à quoi ça ressemble. Par exemple, on pourrait choisir de fournir une petite amélioration sur une solution approuvée, ce qui sera beaucoup moins excitant que de donner un point d'apprentissage à quelqu'un sur une solution en train d'être désapprouvée et qui pourrait donc justifier un exemple plutôt qu'un lien.
• Classe les commentaires par ordre d'importance, le premier commentaire étant le plus important, et le dernier le moins important.
• Garde un nombre de commentaires gérable. Vise un à trois commentaires par itération.
• N'ajoute pas le même commentaire deux fois dans une même analyse. Ajouter le même commentaire avec des paramètres différents n'est pas considéré comme un doublon.
• Envisage de ne commenter que le formatage si le formatage ou le linting fait partie intégrante du langage. Quand c'est possible, guide les apprenants vers des outils d'auto-formatage et/ou renvoie vers un guide de style officiel.

Premiers exercices

Pour les premiers exercices d'un parcours, ce qui suit est particulièrement important :

• Reste relativement bref, en évitant un mur de texte ou de les submerger de conseils. S'ils vivent une bonne expérience dès le premier exercice, ils reviendront et tu auras bien d'autres occasions de donner un retour sur tout ce que tu as remarqué.
• N'explique pas exagérément un concept : ne t'étends pas sur les mécanismes sous-jacents des compilateurs et autres. Ici, il s'agit plutôt du fait que c'est l'un des premiers exercices du parcours de langage, et à ce stade, un retour plus court et plus direct est plus utile.
• Donne un lien qui montre exactement comment faire pour le concept, dans un style tutoriel. C'est-à-dire : montrer comment faire les choses, pas discuter du pourquoi. Cela peut signifier que la documentation officielle du langage ne suffit pas, car elle est souvent une référence de code et ne montre pas comment l'utiliser ni comment ça marche. Cependant, tu ne dois fournir un lien que pour une exploration plus approfondie. La personne doit pouvoir comprendre ce que tu veux dire directement à partir de la réponse, sans suivre le lien.

Exemples

En JavaScript, un apprenant a écrit une constante de haut niveau avec let.

<!-- not following these guidelines -->

As you know, everyone uses const, you shouldn't use let or var.

Ce commentaire ne suit pas ces consignes pour les raisons suivantes :

• L'action vient après l'« explication ».
• « As you know » : on ne sait pas si l'apprenant le sait.
• « you shouldn't » : tu n'as pas besoin du « you » pour formuler cette remarque.
• « everyone uses const » : ce n'est pas vrai et cela peut donner à l'apprenant l'impression d'avoir fait quelque chose de terriblement mal.
• Il manque une véritable explication de pourquoi ce conseil est donné.

<!-- better -->

Prefer `const` and `let` over `var`. The `const` declaration stops a variable
from being accidentally reassigned, which provides safety, and reduces
cognitive load for someone reading the code. [This article](https://medium.com/javascript-scene/javascript-es6-var-let-or-const-ba58b8dcde75)
explains the difference between the three.

En Go, un apprenant a créé une erreur personnalisée au lieu d'utiliser celles intégrées :

<!-- not following these guidelines -->

I see you are creating a custom `error`. This is perfectly fine! If you did not
know about `errors.New` and `fmt.Errorf` have a look at them as they are much
simpler ways to create an error. Custom errors are helpful if you want to check
if an error is of a certain type later.

Ce commentaire ne suit pas ces consignes pour les raisons suivantes :

• « I see » : l'analyseur n'est pas une personne : évite « I ».
• « This is perfectly fine! » : apparemment, ça ne l'est pas, sinon la formule rassurante n'était pas nécessaire. On peut probablement l'enlever complètement ; si tu veux donner une astuce générique sur quelque chose qui existe, tu peux dire exactement ça : « An alternative, equally valid way of doing x is y. »
• « If you did not know about » : enlève ce groupe de mots trop verbeux.

<!-- better -->

A custom `error` is typically used to provide custom behavior, or to distinguish
on type later. For simpler cases, it's more common to rely on `errors.New` or
`fmt.Errorf`. This [in-depth article](https://golangbot.com/custom-errors/) about
custom errors might be interesting.

CI

Comme les commentaires ne se trouvent pas dans le même dépôt que l'analyseur, chaque analyseur devrait avoir une CI qui vérifie si les commentaires utilisés dans cet analyseur spécifique (ceux qui peuvent devenir une sortie) sont des commentaires sur la branche main, sur le dépôt exercism/website-copy.

Au moment de la rédaction, ce ticket suit l'état d'une éventuelle généralisation de cette CI, s'il y en a une.