Varias veces hemos hablado ya de lo importante que es escribir código limpio, que sea entendible por tus compañeros de equipo o por ti mismo en futuros mantenimientos.
El flujo de trabajo de un programador incluye utilizar algún sistema de control de código fuente, siendo Git la opción más común hoy en día.
Cuando hacemos una contribución al repositorio del proyecto (commit), se requiere acompañarla de una breve explicación que sirva de guía a rasgos generales de las modificaciones realizadas. Aunque no es estrictamente código, estos mensajes que acompañan a un commit también deberían seguir unas mínimas buenas prácticas para no mermar su utilidad.
Estructura de un mensaje de commit
Es bastante común obviar es que no necesariamente hay que limitarse a escribir un mensaje de una línea que contenga toda la información. Se puede escribir un título con el resumen a grandes rasgos, y luego podemos complementar la información aportando un cuerpo al mensaje, tan sencillo como dejar una línea en blanco entre uno y otro.
De esta manera, podemos dividir en 3 secciones un mensaje: asunto, cuerpo y pie, siendo el asunto lo más relevante y lo único imprescindible.
Asunto: Breve resumen de los cambios realizados
Cuerpo: Explicación opcional más detallada que aporta contexto e información adicional.
Pie: Datos opcionales como IDs de issue trackers
¿Hasta que punto es importante el contenido de un mensaje de commit?
La principal utilidad de un mensaje de commit no es explicar cuáles son los cambios que contiene ese commit, ya que eso se puede consultar en el historial. La principal utilidad del mensaje de commit es explicar la razón que hay detrás de esos cambios.
Siempre podemos recurrir al historial para descubrir qué cambios se han hecho, pero solo un mensaje coherente puede decirte el por qué.
Por tanto, cuando la razón de un cambio no quede suficientemente clara con el asunto y el diff del commit, podemos usar el cuerpo del mensaje para aportar un contexto y un por qué a dichos cambios.
¿Cómo escribir un buen mensaje de commit?
El asunto (subject)
Debe comenzar con letra mayúscula y terminar sin punto. Piensa, por ejemplo, en como escribirías un asunto de un correo electrónico.
Por otro lado, no debería contener más de 50 caracteres. Esto garantiza legibilidad de cara a las herramientas que muestran los mensajes, y provoca al autor la necesidad de sintetizar de forma concisa. No hace falta que te pongas a contar letras, es una orientación.
Por último, debe estar escrito en tiempo verbal imperativo. Por ejemplo:
- Add new field address on user entity
- Fix bug where user can’t signup
De hecho, internamente Git usa el imperativo en los mensajes que auto-genera (ej: Merge branch ‘myfeature’).
Para que resulte más sencillo, podemos aplicar este truco que consiste en concatenar una frase antes del texto y comprobar que tiene sentido:
- If applied, this commit will your subject line here
- Ej: If applied, this commit will Add list of videos on movie details
El cuerpo (body)
Si el contenido y contexto del commit se puede explicar en el asunto, no es necesario incluir un cuerpo.
Sin embargo, si vemos adecuado incluir más información, para separar el asunto del cuerpo hay que insertar una línea en blanco entre ambos.
Al contrario que el asunto, el contenido (cuerpo) sí termina las frases con un punto, y podemos utilizar varias frases e incluso crear listas con guiones o asteriscos.
Dependiendo de las herramientas que utilice tu equipo para consultar los mensajes, puede que sea necesario limitar a 72 el número de caracteres por línea, ya que Git no lo wrapea de manera automática. Yo personalmente esto no lo hago porque acostumbro a utilizar IDEs o interfaces web para hacer estas consultas que se encargan de mostrar las líneas de manera legible.
Pero lo más importante del cuerpo del mensaje es utilizarlo para explicar el qué y el por qué, en lugar de el cómo. Se trata de explicar el problema que el commit resuelve; el código en sí ya indica el cómo, así que hay que centrarse en aportar contexto para el por qué. Esto está especialmente recomendado si existen soluciones alternativas a la implantada, ya que así los futuros colaboradores del proyecto pueden saber por qué se escogió esa solución frente a las otras opciones.
El pie (footer)
En las últimas líneas se pueden poner referencias a los ids de los issues afectados o relacionados.
Plantilla de un mensaje de commit
Extracto de los cambios en 50 caracteres o menos
Texto explicativo más detallado, solo si es necesario. La línea en blanco que separa el asunto del resto del texto es crucial (a no ser que omitas el cuerpo y el mensaje solo tenga asunto); algunas herramientas pueden mostrar información alterada si omites la línea en blanco de separación.
También se pueden añadir más párrafos, separados igualmente por una línea en blanco.
- Se pueden añadir listas
- Para las listas se usan guiones o asteriscos (como en Markdown)
En el pie, se pueden poner referencias a los ids de los issue trackers, por ejemplo:
Resolves: #123 See also: #456, #789
Conclusión
La mayoría de los lenguajes de programación tienen definidas y aceptadas unas convenciones, que pueden variar, pero lo normal es que un mismo equipo siga un mismo estilo. En los mensajes que usamos en nuestras contribuciones al repositorio ocurre lo mismo, puede haber variaciones de lo que hemos aconsejado en este artículo, pero lo importante es mantener una homogeneidad.
Sabremos si lo estamos haciendo bien si el hilo de mensajes del historial de nuestro proyecto tiene coherencia y consistencia.
En este artículo sólo hemos tratado el estilo de los mensajes de commit, pero si estás interesado saber más buenas prácticas usando Git, te recomiendo saber cuándo hacer un commit y escoger un buen flujo de trabajo.
Nota: Este texto fue publicado originalmente en el blog de Kirei Studio.