Cómo escribir comentarios en 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 guarda como documentos 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 específico del repositorio website-copy.

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

Redacción

• Evita los comentarios innecesariamente largos. Sé breve.
• Adopta un tono neutral y observacional, evitando las afirmaciones cargadas de juicio y las generalizaciones.
• Haz explícita la recomendación.
• Cuando sea posible, pon la recomendación primero 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 pueden dar la impresión de que se juzga a la persona en lugar del código.
• Evita palabras como «just», «simply» u «obviously», que pueden sonar condescendientes: si el comentario es necesario, entonces obviously no era obvious.
• Evita dar por sentado lo que las personas saben y lo que no. 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, no significa que la persona lo entienda.

Directrices

• Apunta a la fluidez, no a la competencia: el objetivo de un track de lenguaje en Exercism es dar a las personas una forma de alcanzar un alto nivel de fluidez con un bajo nivel de competencia. Buscamos fluidez en la sintaxis, los modismos y la biblioteca estándar del lenguaje.
• Sugiere código idiomático cuando sea posible, donde idiomático es el código que escribirían casi todos los desarrolladores (que no son aficionados) que escriben código en ese lenguaje. Si haces una sugerencia poco 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 las personas puedan reconocer esos conceptos en otros lugares y también investigarlos por su cuenta.
• No des la solución como consejo general para toda la mentoría de Exercism. El aprendizaje se afianza cuando las personas descubren la respuesta por sí mismas. Esa es una experiencia enormemente estimulante, y el subidón emocional la hace memorable. Sin embargo, si el descubrimiento no provoca un subidón de dopamina, tiene todo el sentido mostrar cómo se ve. Por ejemplo, podríamos optar por ofrecer una pequeña mejora en una solución aprobada, lo cual será mucho menos emocionante que dar un punto de aprendizaje sobre una solución que se está rechazando y que, por lo tanto, puede ameritar un ejemplo en lugar de un enlace.
• Ordena los comentarios por importancia: el primer comentario es el más importante y el último es el menos importante.
• Mantén un número manejable de comentarios. Apunta a entre uno y tres comentarios por iteración.
• No agregues el mismo comentario dos veces en un mismo análisis. Agregar el mismo comentario con distintos parámetros adjuntos no se considera un duplicado.
• Considera comentar solo sobre el formato si el formateo o el linting son parte integral del lenguaje. Cuando sea posible, guía a los estudiantes hacia herramientas de autoformateo y/o enlaza a cualquier guía de estilo oficial.

Los primeros ejercicios

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

• Que sea relativamente corto, evitando un muro de texto o abrumarlos con consejos. Si tienen una gran experiencia en el primer ejercicio, volverán, y tendrás muchas más oportunidades de dar retroalimentación sobre todas las cosas que notaste.
• No expliques un concepto en exceso: no profundices en los mecanismos internos de los compiladores y ese tipo de cosas. En este caso se trata más bien de que es uno de los primeros ejercicios del track de lenguaje, y en esta etapa la retroalimentación es más útil si es más breve y más directa.
• Da un enlace que muestre exactamente cómo aplicar el concepto, al estilo de un tutorial. Es decir: mostrar cómo hacer las cosas, no discutir por qué. 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 dar un enlace para una exploración más profunda. La persona debería poder entender lo que quieres decir directamente a partir de la respuesta, sin seguir el enlace.

Ejemplos

En JavaScript, un estudiante escribió 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 las siguientes razones:

• 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 hizo algo terriblemente mal.
• Carece de 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 creó un error personalizado en lugar de usar los que vienen 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 las siguientes razones:

• «I see»: el analizador no es una persona: evita «I».
• «This is perfectly fine!»: al parecer no lo es, de lo contrario la frase tranquilizadora no sería necesaria. Probablemente se pueda omitir por completo; 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»: omite este grupo de palabras innecesariamente extenso.

<!-- 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 CI que verifique que los comentarios usados en ese analizador específico (los que pueden convertirse en salida) sean comentarios de la rama main del repositorio exercism/website-copy.

Al momento de escribir esto, este issue hace seguimiento al estado de cualquier generalización de esta CI, si la hay.