Scrivere i commenti dell'analizzatore

Questo documento fornisce informazioni e linee guida su come scrivere i commenti prodotti dall'analizzatore.

Contenuti

I contenuti dei commenti dell'analizzatore sono archiviati come documenti Markdown nel repo exercism/website-copy. I commenti contengono una stringa puntatore, formattata come <track-slug>.<exercise-slug>.<comment-slug>, che rimanda a uno specifico documento Markdown nel repo website-copy.

Per esempio, ruby.two-fer.string-interpolation fa riferimento a https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md.

Formulazione

• Evita commenti inutilmente prolissi. Sii conciso.
• Sii neutrale nell'osservare: evita affermazioni di giudizio e generalizzazioni.
• Rendi esplicito il consiglio.
• Quando possibile, metti prima il consiglio, poi la spiegazione.
• Evita «me», «I», «we», ecc., perché il bot non è una persona.
• Evita «you» e «your code», perché a volte possono sembrare un giudizio sulla persona invece che sul codice.
• Evita parole come «just», «simply», «obviously», che possono risultare supponenti: se il commento è necessario, allora obviously non era poi così ovvio.
• Evita di dare per scontato quello che le persone sanno e quello che non sanno. L'unica eccezione è la conoscenza acquisita dagli esercizi core già completati. Evita «as you know», «as you remember», «as you learned», «now that we all understand x»: anche se qualcosa è stato detto, non è detto che la persona lo abbia capito.

Linee guida

• Punta alla fluidità, non alla padronanza: l'obiettivo di un track di linguaggio su Exercism è dare alle persone un modo per raggiungere un alto livello di fluidità con un basso livello di padronanza. Puntiamo alla fluidità nella sintassi, negli idiomi e nella libreria standard del linguaggio.
• Suggerisci codice idiomatico quando possibile: idiomatico è il codice che scriverebbero quasi tutti gli sviluppatori (non i dilettanti) che programmano in quella lingua. Se il suggerimento non è idiomatico, dillo e spiega perché potrebbe comunque essere utile.
• Dai un nome alla differenza tra quello che la persona sta facendo e quello che è «idiomatico» nella lingua.
• Usa i termini appropriati e la nomenclatura corretta, così le persone possono riconoscere quei concetti altrove e possono anche approfondirli da sole.
• Non dare la soluzione come consiglio generale per tutto il mentoring su Exercism. L'apprendimento resta impresso quando le persone scoprono la risposta da sole. È un'esperienza tremendamente esaltante, e la scossa emotiva la rende memorabile. Però, se la scoperta non scatena una scarica di dopamina, ha perfettamente senso mostrare come si fa. Per esempio, potremmo scegliere di fornire un piccolo miglioramento su una soluzione approvata: sarà molto meno entusiasmante che offrire a qualcuno uno spunto di apprendimento su una soluzione che viene disapprovata e che quindi merita un esempio anziché un link.
• Ordina i commenti per importanza: il primo commento è il più importante, l'ultimo è il meno importante.
• Mantieni un numero gestibile di commenti. Punta a un numero di commenti tra uno e tre per iterazione.
• Non aggiungere lo stesso commento due volte in una stessa analisi. Aggiungere lo stesso commento con parametri diversi non è considerato un duplicato.
• Valuta se commentare solo la formattazione se la formattazione o il linting sono parte integrante della lingua. Quando possibile, indirizza gli studenti verso strumenti di formattazione automatica e/o rimanda a una guida di stile ufficiale.

I primi esercizi

Per i primi esercizi di un track, quanto segue è particolarmente importante:

• Sii relativamente breve: evita un muro di testo o di sommergerli di consigli. Se vivono una bella esperienza nel primo esercizio, torneranno, e avrai molte più occasioni per dare un feedback su tutto quello che hai notato.
• Non spiegare un concetto in modo eccessivo: non entrare nei dettagli dei meccanismi interni dei compilatori e simili. Qui conta di più il fatto che questo è uno dei primi esercizi del track di linguaggio: in questa fase un feedback è più utile se è breve e più direttivo.
• Fornisci un link che mostri esattamente come mettere in pratica il concetto, in stile tutorial. Cioè: mostrare come si fanno le cose, non discutere il perché. Questo può significare che la documentazione ufficiale della lingua non basta, perché spesso è un riferimento per il codice e non mostra come usarlo e come funziona. Però dovresti fornire un link solo per un approfondimento. La persona deve poter capire cosa intendi direttamente dalla risposta, senza seguire il link.

Esempi

In JavaScript, uno studente ha scritto una costante di primo livello con let.

<!-- not following these guidelines -->

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

Questo commento non segue queste linee guida per i seguenti motivi:

• L'azione viene dopo la «spiegazione».
• «As you know»: non sappiamo se lo studente lo sa.
• «you shouldn't»: non serve il «you» per formulare questa affermazione.
• «everyone uses const»: non è vero e può far sentire lo studente come se avesse fatto qualcosa di terribilmente sbagliato.
• Manca una vera spiegazione del perché viene dato quel consiglio.

<!-- 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.

In Go, uno studente ha creato un errore personalizzato invece di usare quelli predefiniti:

<!-- 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.

Questo commento non segue queste linee guida per i seguenti motivi:

• «I see»: l'analizzatore non è una persona, evita «I».
• «This is perfectly fine!»: a quanto pare non lo è, altrimenti la rassicurazione non sarebbe necessaria. Probabilmente si può togliere del tutto; se vuoi dare un consiglio generico su qualcosa che esiste, puoi dirlo esattamente così: «An alternative, equally valid way of doing x is y.»
• «If you did not know about»: lascia fuori questo gruppo di parole inutilmente prolisso.

<!-- 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

Dato che i commenti non vivono nello stesso repository dell'analizzatore, ogni analizzatore dovrebbe avere una CI che verifica se i commenti usati in quello specifico analizzatore (quelli che possono diventare output) sono commenti presenti sul branch main del repository exercism/website-copy.

Al momento in cui scriviamo, questa issue tiene traccia dello stato di un'eventuale generalizzazione di questa CI.