Escribe comentarios de revisión de código con dictado por voz

Un comentario útil en una revisión de código no se limita a señalar lo que parece incorrecto. Describe el comportamiento, explica por qué importa e indica el siguiente paso. Escribir esas explicaciones una y otra vez puede interrumpir la revisión. En cambio, una frase como «gestionar el caso vacío» suele dejar demasiadas dudas.

El dictado por voz permite redactar la explicación mientras tienes el razonamiento fresco. En tu Mac, mantén visibles las diferencias del código, abre un borrador de comentario y explica el problema como si hablaras con alguien del equipo. Después, edita el texto antes de publicarlo. Dictar recoge tu explicación; no verifica el código ni decide si un cambio es correcto.

1. Reúne las pruebas antes de hablar

Dedica cada comentario a un solo asunto. Identifica la línea o función relevante, la entrada o situación implicada y el comportamiento observado o esperado. Si no has ejecutado el código, aclara que la duda surge de su lectura. Un posible fallo no debe presentarse como un error reproducido.

Decide también qué respuesta necesitas:

• Cambio necesario: explica el problema concreto o el requisito acordado que debe resolverse antes de aprobar.
• Sugerencia: deja claro que la mejora es opcional.
• Pregunta: pide contexto cuando aún no sabes si hace falta modificar algo.

Sigue las convenciones de revisión de tu equipo. Una preferencia personal no se convierte en una condición para aprobar solo porque esté expresada con firmeza.

2. Dicta el razonamiento y añade después las referencias exactas

Habla en tres partes: «En esta situación, he observado este comportamiento. Importa por esta consecuencia. ¿Podríamos hacer o comprobar este cambio?». Haz pausas entre las ideas y mantén un único foco por comentario.

Después de dictar, inserta los identificadores, las rutas de archivos y los fragmentos de código directamente desde la fuente. No dependas solo del reconocimiento de voz para código cuyo significado cambia con un símbolo. Elimina repeticiones y comentarios sobre la persona; describe la implementación y su efecto.

3. Convierte una nota vaga en una indicación concreta

Este ejemplo es ficticio y supone que quien revisa ha reproducido el comportamiento en su entorno local.

Nota inicial: «Hay que arreglar la búsqueda vacía».

Comentario editado:

Cambio necesario — búsqueda vacía: cuando envío una búsqueda que contiene solo espacios, el panel de resultados se queda en estado de carga. Lo he reproducido localmente con el cambio actual. La persona que usa la aplicación no recibe resultados ni una indicación sobre qué hacer después.

¿Podríamos gestionar las entradas que solo contienen espacios antes de iniciar la búsqueda y mostrar el mensaje acordado para una entrada vacía? Añade también una prueba de este caso para comprobar que el estado de carga termina correctamente.

Si solo sospechas que existe un problema, empieza con «Al leer esta rama, parece que…» y pregunta si otra ruta ya contempla el caso. Si el mensaje esperado no está acordado, consulta primero cuál debería ser el comportamiento en vez de inventar un requisito.

4. Reutiliza una plantilla breve

Tipo: [Cambio necesario / sugerencia / pregunta].

Contexto: en [ubicación o situación], [comportamiento observado o duda identificada como tal].

Efecto: esto importa porque [consecuencia concreta].

Siguiente paso: ¿podríamos [cambio específico, comprobación o explicación]?

Pruebas disponibles: [Pasos para reproducir, requisito relevante o resultado de una prueba, si lo hay].

Estos campos ayudan a preparar el borrador; no son encabezados obligatorios para todos los comentarios. Una sugerencia pequeña puede caber en dos frases. Si una cuestión afecta a varios archivos, inclúyela en el resumen de la revisión y enlaza los puntos pertinentes, en lugar de repetirla debajo de cada línea.

5. Revisa el comentario antes de publicarlo

Contrasta nombres, negaciones y términos técnicos con las diferencias del código. Comprueba que un «hace» no se haya convertido en «no hace» y que los resultados de pruebas citados existan realmente. Lee el comentario desde la perspectiva de quien lo recibirá: ¿queda claro qué debe responder o modificar sin tener que adivinar tu intención?

Para tareas relacionadas, consulta las guías sobre descripciones de pull requests e informes de errores claros.

TypeFree es una forma sencilla de convertir la voz en texto editable y escribir más rápido. Dicta el razonamiento de tu próximo comentario de revisión de código, verifica los detalles y publica una respuesta que facilite el siguiente paso.