Cómo escribir mejores commits
Un commit profesional explica qué se cambió y por qué. En este artículo comparto una estructura simple que mejora revisiones, reduce errores y acelera despliegues.
Por qué importa escribir bien los commits
Un commit no es solo una unidad técnica de cambios. Es una pieza de comunicación para tu equipo y para tu yo del futuro. Cuando el mensaje es ambiguo o el cambio mezcla demasiadas cosas, el coste aparece en revisiones lentas, incidentes difíciles de rastrear y rollbacks más arriesgados.
Un historial limpio acelera code reviews, facilita auditorías, mejora la comprensión funcional del producto y reduce tiempo de mantenimiento. En equipos profesionales, la calidad del commit es parte de la calidad del software.
Regla 1: un commit, un objetivo
Cada commit debe responder a una única intención: corregir un bug, implementar una parte concreta de una funcionalidad, o realizar un refactor acotado. Si mezclas varios objetivos, revisar y revertir se vuelve costoso.
- Incorrecto: meter fix + refactor + cambio visual en un solo commit.
- Correcto: separar cada cambio en commits pequeños y coherentes.
Regla 2: mensajes claros con estructura
Usa un asunto breve en imperativo y, cuando sea necesario, un cuerpo explicando el contexto. Si trabajas con convenciones tipo Conventional Commits, mantén consistencia.
feat(auth): validar expiración de token en middleware
Se evita acceso con sesiones expiradas y se devuelve 401 en lugar de 500. Incluye test de integración para ruta protegida.
Regla 3: explica el por qué cuando no sea obvio
El código muestra el qué. El commit debe ayudar con el por qué. Si el cambio responde a rendimiento, seguridad, deuda técnica o una incidencia concreta, déjalo indicado en el cuerpo del commit.
- Referencia issue o ticket cuando exista.
- Describe impacto funcional real para el usuario o el negocio.
- Indica riesgos o decisiones técnicas relevantes.
Checklist antes de hacer push
- El commit representa una sola intención técnica.
- El mensaje se entiende sin abrir el diff.
- El cambio compila y pasa las pruebas aplicables.
- No hay archivos de ruido (logs, formato accidental, temporales).
- El diff es revisable en pocos minutos.
Conclusión
Escribir buenos commits no es burocracia. Es una práctica de ingeniería que mejora colaboración, trazabilidad y velocidad. Si conviertes esta disciplina en estándar de equipo, la calidad del flujo de entrega sube de forma inmediata.