comentarios: convencionales
Comentarios que son fáciles de entender y buscar
Los comentarios como este no son útiles…
Simplemente anotando el comentario con una etiqueta, la intención más evidente y el tono cambia dramáticamente.
Las etiquetas también impulsan al revisor a hacer comentarios más accionables.
sugerencia: Esto no está correctamente redactado.
¿Podemos cambiar esto para que coincida con el texto de la página de marketing?
Etiquetar comentarios fomenta la colaboración y ahorra horas de malentendidos y falta de comunicación. ¡También son analizables por computadoras!
Ejemplos
sugerencia: Evitemos usar esta función específica…
Si hacemos referencia a una función marcada como “Obsoleta”, es casi seguro que no funcionará correctamente tarde o temprano.
Audiencia objetivo
Los Comentarios Convencionales son un estándar para formatear comentarios de cualquier tipo de proceso de revisión/retroalimentación, como:
Formato
Adherirse a un formato consistente mejora las expectativas del lector y la legibilidad por computadoras. Este es el formato que proponemos:
<etiqueta> [decoraciones]: <asunto>
[discusión]
- etiqueta - Es una etiqueta única que especifica qué tipo de comentario se está dejando.
- asunto - Es el mensaje principal del comentario.
- decoraciones (opcional) - Son etiquetas adicionales que decoran el comentario. Están rodeadas por paréntesis y separadas por comas.
- discusión (opcional) - Contiene evidencia, contexto del comentario, argumentos adicionales y cualquier otra cosa para ayudar a comunicar el “por qué” y los “próximos pasos” para resolver el comentario.
Por ejemplo:
pregunta (no bloqueante): En este punto, ¿importa qué hilo ha ganado?
¿Quizás para prevenir una condición de carrera deberíamos seguir haciendo bucles hasta que todos hayan ganado?
Puede ser analizado automáticamente como:
{
"label": "pregunta",
"subject": "En este punto, ¿importa qué hilo ha ganado?",
"decorations": ["no bloqueante"],
"discussion": "¿Quizás para prevenir una condición de carrera deberíamos seguir haciendo bucles hasta que todos hayan ganado?"
}
Etiquetas
Recomendamos vehementemente usar las siguientes etiquetas:
NOTA: Para mantener la consistencia, te recomendamos usar las etiquetas en inglés. Esto facilita la estandarización entre herramientas y equipos multilingües. Si esto no es relevante para tu equipo, no dudes en usar la traducción que prefieras.
| praise: elogio: |
Los elogios destacan algo positivo. Intenta dejar al menos uno de estos comentarios por revisión. Busca aspectos que puedas elogiar sinceramente en vez de dejar elogios falsos (que pueden ser perjudiciales). |
| nitpick: detalle: |
Los detalles son solicitudes triviales basadas en preferencias. Estos deberían ser no bloqueantes por naturaleza. |
| suggestion: sugerencia: |
Las sugerencias proponen mejoras a la propuesta original. Es importante ser explícito y claro sobre qué se está sugiriendo y por qué es una mejora. Considera usar parches y las decoraciones bloquea o no bloquea para comunicar mejor tu intención. |
| issue: problema: |
Los problemas destacan defectos específicos con la propuesta bajo revisión. Estos pueden ser visibles para el usuario o no. Se recomienda vehementemente emparejar este comentario con una sugerencia. Si no estás seguro de si existe un problema o no, considera dejar una pregunta. |
| todo: pendiente: |
Los pendientes son cambios triviales pero necesarios. Distinguir los pendientes de los problemas o sugerencias ayuda a dirigir la atención del lector a comentarios que requieren mayor esfuerzo. |
| question: pregunta: |
Las preguntas son apropiadas si tienes una preocupación pero no estás seguro si es relevante o no. Pedir aclaraciones o investigación al autor puede llevar a una resolución rápida. |
| thought: pensamiento: |
Los pensamientos representan una idea que surgió durante la revisión. Estos comentarios no bloquean la propuesta pero son extremadamente valiosos y pueden conducir a iniciativas más enfocadas y oportunidades de mentoría. |
| chore: quehacer: |
Los quehaceres son tareas simples que deben hacerse antes de que la propuesta pueda ser “oficialmente” aceptada. Normalmente, estos comentarios hacen referencia a algún proceso común. Intenta dejar un enlace a la descripción del proceso para que el lector sepa cómo resolver la tarea. |
| note: nota: |
Las notas nunca bloquean la propuesta y simplemente destacan algo a lo que el autor debería notar. |
Si prefieres aún más expresivo con tus etiquetas, también puedes considerar:
| typo: errata: |
Los comentarios de erratas son como tarea:, donde el problema principal es un error de ortografía. |
| polish: pulir: |
Los comentarios de pulido son sugerencias en las que no hay nada necesariamente incorrecto con el cambio propuesto, pero existen formas inmediatas de mejorar su calidad. |
| quibble: disputa: |
Las disputas son muy parecidas a detalle: y nitpick:, excepto que no evocan imágenes de piojos y prácticas de higiene animal. |
Siéntete libre de desviarte de esta lista específica de etiquetas si parece apropiado.
Decoraciones
Las decoraciones dan contexto adicional a un comentario. Ayudan a clasificar aún más los comentarios que tienen la misma etiqueta (por ejemplo, una sugerencia acerca de un riesgo de seguridad en contraposición a una sugerencia acerca de unas pruebas automátizadas).
sugerencia (seguridad): Me preocupa un poco que estemos implementando nuestra propia función de purificación DOM aquí…
¿Podríamos considerar usar el framework en su lugar?
Las decoraciones pueden ser específicas para cada organización. Si es necesario, recomendamos establecer un conjunto mínimo de decoraciones (dejando espacio para la discreción) sin ambigüedad.
Las posibles decoraciones incluyen:
| (non-blocking) (no bloquea) |
Un comentario con esta decoración no debería impedir que la propuesta bajo revisión sea aceptada. Esto es útil para organizaciones que consideran cualquier comentario como razón para bloquear una propuesta. |
| (blocking) (bloquea) |
Esta decoración indica que el comentario debe impedir que los cambios propuestos bajo revisión sean aceptados hasta que se resuelva. Es útil para equipos donde los comentarios no se consideran bloqueantes por defecto. |
| (if-minor) (si-menor) |
Esta decoración da cierta libertad al autor para que resuelva el comentario solo si los cambios terminan siendo menores o triviales. |
Agregar una decoración a un comentario debería mejorar la comprensión y mantener la legibilidad. Tener una lista de muchas decoraciones en un comentario entraría en conflicto con este objetivo.
Más ejemplos
detalle: pequeña estrella => pequeño murciélago
¿Podemos actualizar también las otras referencias?
quehacer: Ejecutemos el trabajo de CI jabber-walk para asegurarnos de que esto no rompa ninguna referencia conocida.
Aquí están los documentos para ejecutar este trabajo. ¡No dudes en contactarnos si necesitas ayuda!
¿Quieres colaborar?
Si tienes una sugerencia, comentario, idea, o algo completamente diferente, por favor visita el proyecto GitLab para colaborar. ¡Los issues y Merge Requests son bienvenidos!
Proyectos y herramientas desarrolladas por la comunidad
Consulta esta página para ver una muestra de proyectos y herramientas desarrolladas por la comunidad.
Mejores prácticas para comunicación escrita
Consulta esta página para conocer algunas ideas generales y principios sobre cómo mejorar la comunicación escrita en revisiones.
Arte previo
Los personajes utilizados en los ejemplos están adaptados respetuosamente de Alicia en el País de las Maravillas de Lewis Carroll, ilustrado por John Tenniel.
Traducido por Lucas Bonanni