4 min read
Son las 11pm de un jueves, producción está fallando, y estás corriendo git log para entender qué cambió en las últimas semanas. Y ahí te encontrás con esto:
fix
cambios
update
asdasd
arreglo definitivo (creo)
Ninguno de esos mensajes te dice nada. No sabés qué se arregló, por qué, ni si ese “arreglo definitivo (creo)” tiene algo que ver con el bug que estás cazando ahora. El commit message es la única documentación que sobrevive garantizada al paso del tiempo — el código cambia, los comentarios se desactualizan, pero el historial de Git queda ahí, intacto, esperando a que alguien (probablemente vos mismo, seis meses después) lo necesite.
Por qué a nadie le importa hasta que sí
Escribir un buen commit message toma treinta segundos extra. En el momento, se siente como fricción innecesaria — el código ya funciona, ¿para qué perder tiempo describiéndolo? El problema es que ese costo lo pagás una vez, pero el beneficio lo cobrás decenas de veces: cada git blame que alguien corre para entender por qué una línea existe, cada release note que se arma revisando el historial, cada bisección (git bisect) buscando qué commit introdujo una regresión.
La estructura que funciona
No hace falta inventar nada — el formato de Conventional Commits se volvió un estándar de facto por una buena razón: es simple y cubre el 90% de los casos.
<tipo>(<alcance opcional>): <resumen en imperativo, menos de 50 caracteres>
<cuerpo opcional: el porqué, no el qué>
<footer opcional: referencias a tickets, breaking changes>
Los tipos más usados: feat (nueva funcionalidad), fix (corrección de bug), refactor (cambio interno sin alterar comportamiento), docs (documentación), test (pruebas), chore (tareas de mantenimiento).
Un ejemplo real:
fix(checkout): evitar doble cobro en reintentos de pago
El servicio de pagos podía procesar la misma transacción dos veces
cuando el cliente reintentaba tras un timeout de red, porque no
validábamos idempotencia por orderId.
Se agregó una clave de idempotencia basada en orderId + timestamp
antes de llamar al gateway de pagos.
Fixes: JIRA-4821
Compará ese mensaje contra un simple “fix payment bug”. El primero le ahorra a la próxima persona — otra vez, probablemente vos — quince minutos de arqueología en el código.
La regla de oro: el qué está en el diff, el porqué va en el mensaje
Este es el error más común incluso en mensajes “bien escritos”: describir qué cambió, cuando el código ya lo muestra perfectamente.
- Redundante: “Se cambió el método calculateTotal para que use BigDecimal en lugar de double” — eso ya lo veo en el diff.
- Útil: “Se usa BigDecimal para evitar errores de redondeo en montos grandes, reportados por finanzas en facturas sobre $10,000” — eso el diff no lo dice.
El diff te muestra el qué. El mensaje de commit existe para explicar el porqué, que es exactamente lo que se pierde con el tiempo si no lo dejás por escrito.
Guía rápida para escribir mejores commits
- Usá el imperativo: “Agrega validación”, no “Agregando validación” ni “Agregué validación”. Es la convención que usa el propio Git en sus mensajes automáticos (“Merge branch…”).
- Un commit, un cambio lógico: si tu mensaje necesita la palabra “y” para describir lo que hiciste (“arregla el bug Y refactoriza el servicio”), probablemente sean dos commits.
- El resumen cabe en una línea de terminal: menos de 50 caracteres para el título. Si necesitás más espacio, usá el cuerpo del mensaje.
- Referenciá el ticket, no reemplaces el mensaje con él: “JIRA-4821” solo, sin contexto, obliga a abrir Jira para entender el cambio. El ticket complementa, no sustituye.
Conclusión
El commit message es la nota que le dejás a la persona que va a heredar tu código — y las probabilidades de que esa persona seas vos mismo, sin memoria del contexto, son altísimas. Treinta segundos extra al escribir, multiplicados por cero minutos perdidos investigando después. Es una de las inversiones con mejor retorno que existen en el día a día de programar.
Recordá suscribirte aquí para recibir los próximos posts directamente en tu correo.
Referencias:
Conventional Commits — https://www.conventionalcommits.org/
Clean Code — Robert C. Martin