Escribir comentarios de los analizadores

Este documento ofrece información y directrices sobre cómo escribir los comentarios que produce el analizador.

Contenido

El contenido de los comentarios del analizador se almacena como documento Markdown en el repositorio exercism/website-copy. Los comentarios contienen una cadena de referencia, con el formato <track-slug>.<exercise-slug>.<comment-slug>, que enlaza con un documento Markdown concreto del repositorio website-copy.

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

Redacción

• Evita comentarios innecesariamente prolijos. Sé conciso.
• Sé neutral y observacional; evita afirmaciones con carga y generalizaciones.
• Formula la recomendación de forma explícita.
• Cuando sea posible, pon primero la recomendación y después la explicación.
• Evita «me», «I», «we», etc., porque el bot no es una persona.
• Evita «you» y «your code», porque a veces puede parecer que se juzga a la persona en lugar de al código.
• Evita palabras como «just», «simply» u «obviously», que pueden sonar condescendientes: si el comentario es necesario, obviamente no era obvio.
• Evita hacer suposiciones sobre lo que la gente sabe y no sabe. La única excepción es el conocimiento de ejercicios core ya completados. Evita «as you know», «as you remember», «as you learned», «now that we all understand x», porque aunque algo se haya dicho, la persona no necesariamente lo entiende.

Pautas

• Busca la fluidez, no el dominio: el objetivo de un track de un lenguaje en Exercism es dar a la gente una forma de alcanzar un alto nivel de fluidez con un bajo nivel de dominio. Buscamos fluidez en la sintaxis, los modismos y la biblioteca estándar del lenguaje.
• Sugiere código idiomático siempre que sea posible, entendiendo por idiomático el código que escribirían casi todos los desarrolladores (no aficionados) que escriben código en ese lenguaje. Si haces una sugerencia que no es idiomática, menciónalo y explica por qué la sugerencia podría seguir siendo útil.
• Nombra la diferencia entre lo que hace la persona y lo que es «idiomático» en el lenguaje.
• Usa los términos y la nomenclatura adecuados, para que la gente pueda reconocer esos conceptos en otros sitios y también pueda investigarlos por su cuenta.
• No des la solución como consejo general para toda la mentoría de Exercism. El aprendizaje se fija cuando las personas descubren la respuesta por sí mismas. Es una experiencia tremendamente estimulante, y el subidón emocional lo hace memorable. Sin embargo, si el descubrimiento no provoca un subidón de dopamina, tiene todo el sentido mostrar cómo es. Por ejemplo, podríamos optar por ofrecer una pequeña mejora a una solución aprobada, lo que será mucho menos emocionante que dar a alguien un punto de aprendizaje sobre una solución que se está rechazando y que, por tanto, puede merecer un ejemplo en lugar de un enlace.
• Ordena los comentarios por importancia, siendo el primer comentario el más importante y el último el menos importante.
• Mantén un número manejable de comentarios. Procura que sean de uno a tres comentarios por iteración.
• No añadas el mismo comentario dos veces en un mismo análisis. Añadir el mismo comentario con distintos parámetros adjuntos no se considera un duplicado.
• Plantéate comentar solo el formato si el formato o el linting son parte integral del lenguaje. Cuando sea posible, guía a los estudiantes hacia herramientas de formato automático o enlaza con cualquier guía de estilo oficial.

Primeros ejercicios

Para los primeros ejercicios de un track, lo siguiente es especialmente importante:

• Que sean relativamente cortos, evitando un muro de texto o abrumarles con consejos. Si tienen una gran experiencia en el primer ejercicio, volverán, y tendrás muchas más oportunidades de dar feedback sobre todas las cosas que hayas notado.
• No expliques un concepto en exceso: no te extiendas sobre los mecanismos internos de los compiladores y ese tipo de cosas. En este caso se trata más bien de que este es uno de los primeros ejercicios del track del lenguaje, y en esta etapa el feedback es más útil si es más corto y más directivo.
• Da un enlace que muestre exactamente cómo hacer ese concepto, al estilo de un tutorial. Es decir: mostrar cómo se hacen las cosas, no debatir el porqué. Esto puede significar que la documentación oficial del lenguaje no sea suficiente, ya que a menudo es una referencia de código y no te muestra cómo usarlo ni cómo funciona. Sin embargo, solo deberías proporcionar un enlace para una exploración más profunda. La persona debería poder entender lo que quieres decir directamente a partir del comentario, sin necesidad de seguir el enlace.

Ejemplos

En JavaScript, un estudiante ha escrito una constante de nivel superior con let.

<!-- not following these guidelines -->

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

Este comentario no sigue estas directrices por los siguientes motivos:

• La acción viene después de la «explicación».
• «As you know»: no sabemos si el estudiante lo sabe.
• «you shouldn't»: no necesitas el «you» para hacer esta afirmación.
• «everyone uses const»: esto no es cierto y puede hacer que el estudiante sienta que ha hecho algo terriblemente mal.
• Le falta una explicación real de por qué se da el consejo.

<!-- 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 estudiante ha creado un error personalizado en lugar de usar los integrados:

<!-- 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 comentario no sigue estas directrices por los siguientes motivos:

• «I see»: el analizador no es una persona: evita «I».
• «This is perfectly fine!»: por lo visto no lo es, de lo contrario no haría falta tranquilizar. Probablemente se pueda quitar del todo; si quieres dar un consejo genérico sobre algo que existe, puedes decir exactamente eso: «An alternative, equally valid way of doing x is y.»
• «If you did not know about»: deja fuera este grupo de palabras tan prolijo.

<!-- 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 los comentarios no viven en el mismo repositorio que el analizador, cada analizador debería tener una CI que compruebe si los comentarios usados en ese analizador concreto (los que pueden convertirse en salida) son comentarios de la rama main del repositorio exercism/website-copy.

En el momento de escribir esto, esta issue hace un seguimiento del estado de cualquier generalización de esta CI, si es que existe.