Cómo usar las funciones de comentarios y revisión en GitHub (Introducción a la revisión de código)

En el artículo anterior, diste el primer paso para contribuir al proyecto de otra persona usando `Fork` y `Pull Request`. Sin embargo, el desarrollo no se completa con solo enviar un Pull Request. Aquí es donde comienza la verdadera esencia del desarrollo en equipo: la revisión de código.

La revisión de código es un proceso en el que otros desarrolladores revisan el código que has escrito y te dan su feedback. Esto permite descubrir errores en una etapa temprana, aprender mejores formas de codificar y mejorar la calidad del código de todo el equipo. En este artículo, explicaremos en detalle cómo comunicarse fluidamente en GitHub y cómo usar las funciones de comentarios y revisión para realizar una revisión de código efectiva.

Conceptos básicos de la revisión de código: Comunicación en Pull Requests

El lugar central para la revisión de código es la página del Pull Request que creaste. En esta página se concentra toda la información sobre tus cambios, y la comunicación aquí es crucial para la calidad del proyecto.

Las funciones de revisión de GitHub se dividen principalmente en dos tipos:

• Comentario (Comment): Una función para publicar preguntas y opiniones de manera informal sobre líneas de código específicas o sobre todo el Pull Request.
• Revisión (Review): Una función para evaluar formalmente todos los cambios y expresar una intención de "Aprobar (Approve)", "Solo comentar" o "Solicitar cambios (Request changes)".

Al utilizar estas dos funciones de manera adecuada, se puede lograr una comunicación fluida.

Cómo usar la función de comentarios

Primero, veamos la función de comentarios, que es fácil de usar.

1. Comentarios en todo el Pull Request

Si deseas hacer preguntas generales sobre todo el cambio o expresar agradecimiento, utiliza el campo de comentarios en la parte inferior de la página del Pull Request. Se encuentra al final de la pestaña "Conversation".

[Imagen: Captura de pantalla del campo de entrada de comentarios en la parte inferior de la página del Pull Request]

Simplemente ingresa tu mensaje en el área de texto y presiona el botón "Comment" para publicar. También puedes notificar (mencionar) a una persona específica escribiendo `@nombredeusuario`.

2. Comentarios en líneas de código específicas

La función más utilizada en la revisión de código es esta, la de comentarios por línea. Es ideal para hacer señalamientos concretos como: "¿No sería mejor que el nombre de la variable en esta parte fuera más claro?".

1. En la página del Pull Request, haz clic en la pestaña "Files changed".
2. Se mostrará una lista de los archivos con cambios. Coloca el cursor del ratón a la izquierda de la línea de código que quieres comentar.
3. Aparecerá un ícono azul con un "+", haz clic en él.
4. Se mostrará un cuadro de texto. Ingresa tu comentario y presiona el botón "Start a review".

[Imagen: Muestra de cómo agregar un comentario a una línea específica en la pestaña "Files changed"]

En este punto, tu comentario aún está en estado "Pendiente (Pending)". Es una práctica común agrupar varios señalamientos y luego enviarlos todos juntos como una revisión.

3. Función de sugerencia de cambios (Suggestion)

Si quieres proponer un código específico diciendo "sería mejor reescribirlo así", haz clic en el ícono "Insert a suggestion" (un símbolo como `+/-`) que se encuentra sobre el campo de comentarios. Se insertará un bloque de código donde podrás escribir directamente tu propuesta de corrección.

[Imagen: Muestra del uso de la función "Insert a suggestion" para proponer una corrección de código en el campo de comentarios]

Al usar esta función, el creador del Pull Request puede aplicar tu sugerencia al código con un solo botón, lo cual es extremadamente conveniente.

Enviar una revisión: Aprobar o solicitar cambios

Una vez que hayas escrito varios comentarios, el paso final es agruparlos y enviarlos como una única "revisión". Haz clic en el botón "Review changes" que se muestra en la esquina superior derecha de la pantalla.

[Imagen: Apuntando al botón "Review changes"]

A continuación, se mostrarán las siguientes tres opciones:

• Comment: Elige esta opción cuando no quieras aprobar ni solicitar cambios, sino simplemente dejar un comentario como feedback. Se usa para "preguntas rápidas" u "opiniones personales".
• Approve: Es una expresión de aprobación que significa "¡Estos cambios son geniales! No hay problemas, está bien hacer el merge".
• Request changes: Es una solicitud de cambios que significa "Estos cambios necesitan correcciones. Por favor, arregla los puntos que señalé antes de hacer el merge".

[Imagen: Ventana modal que muestra las tres opciones al enviar una revisión (Comment, Approve, Request changes)]

Elige la opción adecuada, escribe un comentario de resumen si es necesario y presiona el botón "Submit review". Con esto, tu revisión se enviará formalmente y el creador del Pull Request recibirá una notificación.

Responder a una revisión: Corregir las indicaciones y volver a hacer push

Veamos ahora el caso contrario: cómo responder cuando eres el creador de un Pull Request y recibes una revisión de otra persona.

Paso 1: Confirmar el contenido de los comentarios y discutir
Primero, agradece los señalamientos recibidos. Si hay algo que no entiendes, responde y pregunta. Toda la comunicación queda registrada en el Pull Request.

Paso 2: Corregir el código basándose en las indicaciones
Si estás de acuerdo con las indicaciones del revisor, corrige el código en tu PC local. Es una práctica aún más cuidadosa si trabajas en una nueva rama, como `fix-review-comments`.

Paso 3: Hacer push de los commits adicionales
Una vez que termines de corregir, crea un nuevo commit y haz push a la rama de origen del Pull Request (ej: `fix-typo-in-readme`).

git commit -m "Reflect review comments"

git push origin fix-typo-in-readme

Al hacer push de un nuevo commit, los cambios se reflejan automáticamente en el Pull Request. No es necesario crear un nuevo Pull Request.

Paso 4: Resolver las conversaciones finalizadas
Una vez que hayas atendido todas las indicaciones, presiona el botón "Resolve conversation" debajo de cada comentario para marcar la conversación como resuelta. Esto deja claro de un vistazo qué indicaciones ya han sido atendidas.

[Imagen: El botón "Resolve conversation" es presionado y la conversación se contrae]

Una vez que todas las conversaciones estén resueltas y recibas nuevamente un "Approve" del revisor, finalmente será el momento de hacer el merge.