Escrever comentários de analisadores

Este documento fornece informações e orientações sobre como escrever os comentários produzidos pelo analisador.

Conteúdos

O conteúdo dos comentários do analisador é armazenado como um documento Markdown no repositório exercism/website-copy. Os comentários contêm uma string de apontador, formatada como <track-slug>.<exercise-slug>.<comment-slug>, que aponta para um documento Markdown específico no repositório website-copy.

Por exemplo, ruby.two-fer.string-interpolation refere-se a https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md.

Formulação

• Evita comentários desnecessariamente palavrosos. Sê conciso.
• Sê neutro e observacional; evita afirmações carregadas e generalizações.
• Torna a recomendação explícita.
• Quando possível, coloca a recomendação primeiro e só depois a explicação.
• Evita «me», «I», «we», etc., porque o bot não é uma pessoa.
• Evita «you» e «your code», porque por vezes podem soar a um julgamento da pessoa e não do código.
• Evita palavras como «só», «simplesmente» ou «obviamente», que podem soar condescendentes: se o comentário é necessário, é porque não era assim tão óbvio.
• Evita fazer suposições sobre o que as pessoas sabem e não sabem. A única exceção é o conhecimento de exercícios core já concluídos. Evita expressões como «como sabes», «como te lembras», «como aprendeste», «agora que todos percebemos x», porque, mesmo que algo tenha sido dito, a pessoa não o compreende necessariamente.

Orientações

• Aponta para a fluência, não para a proficiência: o objetivo de um percurso de uma linguagem no Exercism é dar às pessoas uma forma de alcançar um nível elevado de fluência com um nível baixo de proficiência. O que procuramos é fluência na sintaxe, nas expressões idiomáticas e na biblioteca padrão da linguagem.
• Sugere código idiomático sempre que possível, entendendo por idiomático o código que praticamente todos os programadores (não amadores) que escrevem código nessa linguagem escreveriam. Se fizeres uma sugestão que não é idiomática, refere-o e explica porque é que a sugestão pode ainda assim ser útil.
• Dá nome à diferença entre o que a pessoa está a fazer e o que é «idiomático» na linguagem.
• Usa os termos corretos e a nomenclatura adequada, para que as pessoas reconheçam esses conceitos noutros contextos e possam também investigá-los por si próprias.
• Não dês a solução como conselho geral para toda a mentoria no Exercism. A aprendizagem fixa-se quando as pessoas descobrem a resposta por si próprias. É uma experiência tremendamente estimulante, e o impacto emocional torna-a memorável. No entanto, se a descoberta não provocar um pico de dopamina, faz todo o sentido mostrar como é que é. Por exemplo, podemos optar por sugerir uma pequena melhoria numa solução aprovada, o que será muito menos entusiasmante do que dar um ponto de aprendizagem numa solução que está a ser reprovada e que, por isso, pode justificar um exemplo em vez de uma ligação.
• Ordena os comentários por importância, sendo o primeiro comentário o mais importante e o último o menos importante.
• Mantém o número de comentários gerível. Procura fazer entre um e três comentários por iteração.
• Não repitas o mesmo comentário na mesma análise. Adicionar o mesmo comentário com parâmetros diferentes não é considerado uma duplicação.
• Considera comentar apenas a formatação se a formatação ou o linting forem parte integrante da linguagem. Quando possível, orienta os alunos para ferramentas de formatação automática e/ou liga a um guia de estilo oficial.

Primeiros exercícios

Nos primeiros exercícios de um percurso, o seguinte é especialmente importante:

• Sê relativamente breve, evitando uma parede de texto ou sobrecarregar a pessoa com conselhos. Se tiver uma ótima experiência no primeiro exercício, voltará, e terás muitas mais oportunidades de dar feedback sobre tudo o que notaste.
• Não expliques um conceito em excesso: não te aprofundes nos mecanismos subjacentes dos compiladores e afins. Neste caso, trata-se sobretudo de ser um dos primeiros exercícios do percurso da linguagem, e nesta fase o feedback é mais útil se for mais curto e mais direto.
• Inclui uma ligação que mostre exatamente como aplicar o conceito, ao estilo de um tutorial. Ou seja: mostrar como se fazem as coisas, não discutir porquê. Isto pode significar que a documentação oficial da linguagem não chega, porque muitas vezes é uma referência de código e não te mostra como usá-la nem como funciona. No entanto, só deves fornecer uma ligação para uma exploração mais aprofundada. A pessoa deve conseguir perceber o que queres dizer diretamente a partir da resposta, sem seguir a ligação.

Exemplos

Em JavaScript, um aluno escreveu uma constante de nível superior com let.

<!-- not following these guidelines -->

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

Este comentário não segue estas orientações pelos seguintes motivos:

• A ação aparece depois da «explicação».
• «As you know»: não sabemos se o aluno sabe.
• «you shouldn't»: não precisas do «you» para fazer esta afirmação.
• «everyone uses const»: isto não é verdade e pode fazer o aluno sentir que fez algo terrivelmente errado.
• Falta uma explicação real do porquê de o conselho ser dado.

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

Em Go, um aluno criou um erro personalizado em vez de usar os que existem de base:

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

Este comentário não segue estas orientações pelos seguintes motivos:

• «I see»: o analisador não é uma pessoa: evita o «I».
• «This is perfectly fine!»: aparentemente não é, caso contrário o reconforto não era necessário. Isto provavelmente pode ser retirado por completo; se quiseres dar uma dica genérica sobre algo que existe, podes dizer exatamente isso: «An alternative, equally valid way of doing x is y.»
• «If you did not know about»: deixa de fora este grupo de palavras demasiado palavroso.

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

Como os comentários não vivem no mesmo repositório que o analisador, cada analisador deve ter CI que verifique se os comentários usados nesse analisador específico (aqueles que podem tornar-se output) são comentários no ramo main, no repositório exercism/website-copy.

No momento em que escrevemos, esta issue acompanha o estado de qualquer generalização desta CI, se existir.