Quizás seas un cowboy que cabalga sólo y no le das importancia a los comentarios de tus commits en tu repositorio de código, pero cuando se trabaja en equipo estos comentarios son fundamentales para que otros compañeros sepa en qué estado se encuentra el proyecto y lo que se van a encontrar a actualizarlo.

Cuando hacemos hacemos checkout de un proyecto, lo que queremos saber es cuál es el estado del código, es decir, qué funcionalidades nuevas se han incorporado o que comportamientos se han modificado desde la última revisión. Un error en que solemos caer es explicar en los comentarios de commit qué hicimos, pero no qué hace el software.

Los comentarios deben estar más cerca a las historias de usuario que a cuestiones técnicas de métodos, clases o bugs que hemos resuelto. Ojo, no quiere decir que no indiquemos modificaciones de código que puedan influir a nuestros compañeros cuando lo actualicen con el nuestro. Pero lo que esperamos es saber qué hace el software actualmente con el nuevo código que se ha incorporado, las clases que se han modificado y los elementos añadidos o eliminados ya los vemos en la revisión.

Consejos prácticos para mejorar nuestros comentarios en los commits

Leyendo un interesante post que hablaba precisamente sobre repositorios y commits, me encontré con el mismo problema de olvidar explicar el comportamiento del código y centrarse en exceso sobre la descripción de la implementación o qué se hizo. De allí saque algunos consejos prácticos para mejorar nuestros comentarios.

• Hablar sobre las funcionalidades del nuevo código, no sobre ti mismo: no escribir que hiciste, si no describir qué hace el software ahora con estos cambios
• No hablar en pasado, debemos usar el presente y centrarnos en el estado actual.
• Evitar referencia temporales en el commit, la revisión ya incluye la fecha de modificación.

Pero la idea de mejorar nuestros commit va mucho más allá. Ya que dándole una vuelta por completo a la forma de comentar nuestros commit podemos llegar a plantearnos la técnica de escribir los comentarios de commit antes de empezar a codificar ni una sola línea de código.

Beneficios de escribir los comentarios de nuestros commit antes de codificar:

• Estaremos más enfocados durante el desarrollo. El comentario de commit es un resumen de las tareas del to-do que tenemos que implementar. Intentamos no salirnos de la historia de usuario a realizar, sin divagar y haciendo lo que describe ese comentario sin mezclar otras posibles tareas.
• Revisar el commit es mucho más fácil, si tenemos ya una breve visión de lo que tiene que contener.
• A la hora de commitear serás mucho más preciso. Después de un par de horas enfrascado en el código, normalmente no nos apetece pensar demasiado que poner por lo que todo queda en vacíos mensajes de “solucionado el bug…” “mejoras en la clase, blaba, o refactor del método mágico”. Por eso agradecerás haberlo escrito antes.
• Si trabajas con pomodoros, incluso puede servirte para organizar tus commit en sesiones de trabajo haciendo cosas concretas.
• Al final de todo, al tener definida una meta clara, ese commit queda mucho más preciso y podemos fijarnos pequeños hitos o modificaciones que se vean reflejados en el código bien delimitados.

Después de todo, sólo son un par de ideas que puedes poner en practicar o combinar con las tuyas propias. Y si lo de escribir buenos mensajes en los commit no es lo tuyo, puedes seguir recurriendo al generador aleatorio de mensajes de commit, pero luego no te quejes porque te pierdes entre revisiones y no sabes qué hace el código em cada una de ellas.

Vía | Preemptive commit comments
Foto | Generador aleatorio de mensajes de commit