Mensajes de commit de Git para Salesforce

En este artículo, descubre la importancia de escribir buenos mensajes de commit en Git, qué elementos clave deben incluir y cómo pueden beneficiar tanto a tus colegas como a tu yo del futuro.

Estas son nuestras 5 conclusiones clave:

- Un buen mensaje de commit incluye un encabezado, un cuerpo y una firma; el encabezado funciona como un resumen del commit en una sola línea.

- El cuerpo del mensaje de commit debe proporcionar información más detallada sobre los cambios realizados y por qué se hicieron.

- Escribir buenos mensajes de commit puede beneficiar tanto a tus colegas como a tu yo del futuro, al aportar documentación y contexto sobre los cambios realizados.

- El formato es importante: Linus Torvalds recomienda limitar las líneas a unos 74 caracteres.

- Dedicar tiempo a escribir buenos mensajes de commit puede mejorar la calidad del código y ayudarte a comprender mejor el porqué y el cómo de los cambios realizados.

Una consecuencia inesperada y encantadora del cambio hacia la programación colaborativa con Git es Commit Logs From Last Night. Como sugiere el nombre del dominio, este sitio web muestra una lista que se actualiza continuamente con mensajes de commit divertidos de repositorios reales de GitHub. Puedes ver un flujo interminable de desarrolladores que escriben mensajes de commit graciosos y reírte mientras te identificas con su sufrimiento.

Lo gracioso no son las palabrotas, sino la frustración palpable que se nota mientras los desarrolladores programan. Aunque solemos esperar que el código fluya directamente de nuestro cerebro a la terminal, la realidad suele ser más confusa. Programas por prueba y error, y todos hemos estado ahí: hartos y saturados de cafeína a las 2am, preguntándonos por qué este simple cambio no funciona como esperamos. Básicamente, avanzamos a tropezones entre instrucciones de impresión y registros de consola rumbo a la gloria.

XKCD lo resume bastante bien:

Por supuesto, Los mensajes de commit de Salesforce son importantes. Pero la mayoría de las personas no recibe capacitación sobre cómo escribirlos. Aprendemos siguiendo lo que hacen los demás. Y, lamentablemente, muchos improvisamos para llegar a una solución y escribimos mensajes de commit breves y superficiales como los anteriores.

Cómo escribir buenos mensajes de commit

Creador de Git Linus Torvalds de hecho, pasó por GitHub en 2011 para explicar en un commit su opinión sobre cómo debería ser un buen mensaje de commit:

+ línea de encabezado: explica el commit en una línea
+
+ El cuerpo del mensaje de commit consta de unas líneas de texto que explican las cosas
+ con más detalle, posiblemente con algo de contexto sobre el problema
+ que se está corrigiendo, etc., etc.
+
+ El cuerpo del mensaje de commit puede tener varios
+ párrafos; asegúrate de ajustar las líneas y mantener
+ las líneas por debajo de aproximadamente
+ unos 74 caracteres. Así, "git log" mostrará todo
+ correctamente incluso cuando tiene sangría.
+
+ Reported-by: whoever-reported-it
+ Signed-off-by: Your Name <youremail@yourhost.com>

Un buen mensaje de commit tiene 3 elementos clave.

El encabezado

El encabezado es donde la mayoría de las personas empieza (y termina) un mensaje de commit. Es un resumen general de una línea sobre lo que incluye el commit. Es como el asunto de un correo electrónico.

Aunque no hay una regla estricta, muchos blogs como tbaggery sugieren 50 caracteres como una buena extensión para el encabezado. Siempre debes dejar una línea en blanco después del encabezado para que pueda identificarse como el asunto. Tim Pope enumera algunos de los comandos que puedes usar cuando aplicas el formato correcto:

• git log –pretty=oneline
• git rebase –interactive muestra el resumen de cada commit en el editor que abre; si la opción de configuración merge.summary está activada, los resúmenes de todos los commits fusionados se incorporarán al mensaje del commit de fusión
• git shortlog usa las líneas de resumen en la salida que genera, similar a un registro de cambios
• git format-patch, git send-email y otras herramientas relacionadas lo usan como asunto de los correos electrónicos
• los reflogs, un historial local accesible con git reflog que te ayuda a recuperarte de errores tontos, reciben una copia del resumen
• gitk tiene una columna para el resumen
• GitHub usa el resumen en varias partes de su interfaz de usuario

Según Tim Pope:

La distinción entre asunto y cuerpo puede parecer poco importante, pero es uno de los muchos factores sutiles que hacen que trabajar con el historial de Git sea mucho más agradable que con el de Subversion.

Cuerpo del mensaje de commit

La mayoría de las personas nunca pasa del encabezado. Cuando estaba aprendiendo a programar y a usar Git, nunca incluía más que un resumen de una línea. Como casi nunca veía mensajes de commit largos y detallados, supuse que había algún límite estricto en la cantidad de caracteres que podía tener un mensaje de commit. ¡Pero no es así! El propio Linus sugiere incluir descripciones más extensas en nuestros commits para que los demás puedan entender con más detalle qué incluyen.

En muchos proyectos de software, los mensajes de commit son la única documentación. Por eso vale la pena dedicar tiempo a escribir mensajes de commit más detallados. Cuando tus colegas quieran saber por qué algo se implementó de cierta manera, pueden consultar el historial de Git para entender mejor cómo evolucionó una clase de Apex o una página de Visualforce a lo largo del tiempo. Pueden ver cuándo y por qué agregaste un método específico y cuál era su función.

No solo ayuda a tus colegas. Un buen mensaje de commit que hayas escrito puede sacarte de un apuro. Es como si una versión futura de ti regresara y te dijera: «Oye, algún día vas a necesitar saber por qué se agregó este método, y esta es la razón».

Firma

Por último, Linus recomienda incluir «reported by» y «signed off by» al final del mensaje. Esto es menos importante que el encabezado y el cuerpo del mensaje de commit, pero puede ser útil al revisar miles de mensajes de commit.

Formato

Linus sugiere ajustar las líneas a unos 74 caracteres. La mayoría de las terminales tiene 80 columnas, y usar unos 74 caracteres mantiene una sangría adecuada en tu mensaje de commit cuando ejecutas git log. Cualquier editor de texto que uses debería permitirte configurar cuántos caracteres quieres en tus mensajes de commit.

Claridad

Cada vez más equipos de Salesforce están adoptando Git para sus control de versiones.

Escribir buenos mensajes de commit no solo ayuda a tus colegas y a tu yo del futuro. Dedicar tiempo a escribirlos le da a tu cerebro el tiempo y el espacio para pensar en el porqué y el cómo de tu código. Así es más fácil garantizar que tus commits sean de alta calidad y que haya una buena razón detrás de cada cambio. Hacer una pausa de vez en cuando para recopilar este tipo de información es invaluable.

‍