Escrevendo comentários do analisador

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

Conteúdo

O conteúdo dos comentários do analisador fica armazenado como documento Markdown no repositório exercism/website-copy. Os comentários contêm uma string de ponteiro, 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 remete a https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md.

Formulação

• Evite comentários desnecessariamente prolixos. Seja conciso.
• Faça observações neutras, evitando afirmações carregadas e generalizações.
• Deixe a recomendação explícita.
• Quando possível, coloque a recomendação primeiro e a explicação depois.
• Evite "me", "I", "we" etc., já que o bot não é uma pessoa.
• Evite "you" e "your code", porque às vezes isso pode soar como um julgamento da pessoa, e não do código.
• Evite palavras como "just", "simply" e "obviously", que podem soar condescendentes: se o comentário é necessário, é porque obviamente ele não era óbvio.
• Evite presumir o que as pessoas sabem e o que não sabem. A única exceção é o conhecimento de exercícios core já concluídos. Evite "as you know", "as you remember", "as you learned", "now that we all understand x", porque, mesmo que algo tenha sido dito, a pessoa não necessariamente entendeu.

Orientações

• Mire na fluência, não na proficiência: o objetivo de uma trilha de linguagem no Exercism é dar às pessoas uma forma de alcançar um alto nível de fluência com um baixo nível de proficiência. Miramos a fluência na sintaxe, nas expressões idiomáticas e na biblioteca padrão da linguagem.
• Sugira código idiomático quando possível, sendo idiomático o código que praticamente todos os desenvolvedores (que não são hobistas) escreveriam naquela linguagem. Se fizer uma sugestão não idiomática, mencione isso e explique por que a sugestão ainda pode ser útil.
• Nomeie a diferença entre o que a pessoa está fazendo e o que é "idiomático" na linguagem.
• Use os termos corretos e a nomenclatura adequada, para que as pessoas reconheçam esses conceitos em outros lugares e também possam pesquisá-los por conta própria.
• Não dê a solução como orientação geral para toda a mentoria do Exercism. O aprendizado gruda quando a pessoa descobre a resposta por conta própria. É uma experiência tremendamente estimulante, e o impacto emocional faz com que ela fique na memória. No entanto, se a descoberta não desencadear um pico de dopamina, faz todo sentido mostrar como é. Por exemplo, podemos optar por dar uma pequena melhoria em uma solução aprovada, o que será bem menos empolgante do que dar um ponto de aprendizado em uma solução que está sendo reprovada e que, por isso, talvez mereça um exemplo em vez de um link.
• Ordene os comentários por importância, sendo o primeiro o mais importante e o último o menos importante.
• Mantenha um número gerenciável de comentários. Mire em um a três comentários por iteração.
• Não adicione o mesmo comentário duas vezes em uma mesma análise. Adicionar o mesmo comentário com parâmetros diferentes anexados a ele não é considerado uma duplicata.
• Considere comentar apenas sobre formatação se a formatação ou o linting for parte integrante da linguagem. Quando possível, oriente os estudantes a usar ferramentas de formatação automática e/ou forneça um link para o guia de estilo oficial, se houver.

Primeiros exercícios

Para os primeiros exercícios de uma trilha, o seguinte é especialmente importante:

• Mantenha tudo relativamente curto, evitando uma parede de texto ou sobrecarregar a pessoa com conselhos. Se ela tiver uma ótima experiência no primeiro exercício, vai voltar, e você terá muito mais oportunidades de dar feedback sobre tudo o que notou.
• Não explique um conceito em excesso: não se aprofunde nos mecanismos por trás dos compiladores e afins. Nesse caso, o ponto principal é que este é um dos primeiros exercícios da trilha de linguagem, e nessa fase o feedback é mais útil se for mais curto e mais direto.
• Forneça um link que mostre exatamente como fazer o conceito, em um formato de tutorial. Ou seja: mostrar como fazer as coisas, não discutir o porquê. Isso pode significar que a documentação oficial da linguagem não basta, já que muitas vezes ela é uma referência de código e não mostra como usar nem como funciona. No entanto, forneça um link apenas para uma exploração mais aprofundada. A pessoa deve conseguir entender o que você quer dizer direto pela resposta, sem seguir o link.

Exemplos

Em JavaScript, um estudante 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 diretrizes pelos seguintes motivos:

• A ação vem depois da "explicação".
• "As you know": não sabemos se o estudante sabe.
• "you shouldn't": você não precisa do "you" para fazer essa afirmação.
• "everyone uses const": isso não é verdade e pode fazer o estudante sentir que fez algo terrivelmente errado.
• Falta uma explicação de verdade sobre por que o conselho é 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 estudante criou um erro personalizado em vez de usar os já embutidos na linguagem:

<!-- 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 diretrizes pelos seguintes motivos:

• "I see": o analisador não é uma pessoa: evite o "I".
• "This is perfectly fine!": aparentemente não é, senão o consolo não seria necessário. Provavelmente dá para deixar isso de fora por completo; se você quer dar uma dica genérica sobre algo que existe, diga exatamente isso: "An alternative, equally valid way of doing x is y."
• "If you did not know about": deixe de fora esse grupo de palavras prolixo demais.

<!-- 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 ficam no mesmo repositório que o analisador, cada analisador deve ter uma CI que verifique se os comentários usados naquele analisador específico (aqueles que podem virar saída) são comentários presentes na branch main do repositório exercism/website-copy.

No momento em que este texto foi escrito, esta issue acompanha o andamento de qualquer generalização dessa CI, se é que haverá alguma.