Publicado: 15/02/24
| Actualizado: 23/04/24
La importancia que tienen estos mensajes y cómo escribirlos bien
Usar correctamente un sistema de control de versiones es fundamental para tu carrera como developer. Actualmente uno de los más utilizados y que, de hecho, es un requisito excluyente para casi todo puesto de developer, es Git (ojo que Git no es lo mismo que GitHub eh).
Si no sabés que es Git, googlealo. Sí, eso dije. Googlealo. ¿O pensabas que te lo iba a dar todo servido? No señor/a: aprender a googlear correctamente es otra habilidad que tenés que cultivar si querés progresar como dev, al igual que saber usar herramientas de IA (aunque todo esto es para otro post y otro momento). De hecho, googlear es lo que hacemos la mayoría del tiempo los programadores jeje.
Bueno, al punto. Ahora que sabés lo que es Git, seguramente algo que habrás hecho muchas veces es hacer un commit, y junto a ese commit escribiste un mensaje. En mi caso mis commits al principio eran cualquier cosa. Tardaba un montón de tiempo pensando qué poner en ese mensaje sin tener muy claro para qué servían. Supuestamente era para escribir qué cambio o cambios estaba introduciendo en el proyecto/aplicación, pero poco más que eso.
Hoy, dos años después, vengo a compartirte lo que he aprendido sobre los mensajes para los commit en Git, la importancia que tienen y cómo escribirlos correctamente. Este post será un poco una mezcla de experiencia personal e información que encontré en internet con los años, enfocándome principalmente en este gran artículo.
Partamos desde esta base: difícilmente puedas progresar como programador solo/a. La historia muestra que los grandes progresos tecnológicos se lograron en grupo, colaborando. De hecho, ¿porqué te pensás que las empresas buscan gente con experiencia? Mas allá de lo técnico, en parte es porque un programador experimentado sabe trabajar en equipo, junto a otros programadores, con todo lo que ello implica.
Como comentaba al principio, una gran herramienta para lograr este propósito son los sistemas de control de versiones. Entre las muchas ventajas que tiene usar un sistema de estos, se encuentra el de ofrecer contexto al código: saber qué cambios se introdujeron, porqué se introdujeron, qué partes del codebase se vieron afectados y hace cuanto.
Los programadores experimentados en trabajar colaborativamente (ya sea de manera privada en una empresa o en proyectos open source) saben que un mensaje bien elaborado que acompañe a un commit es la mejor forma de comunicar ese contexto a sus compañeros programadores y a sus futuros yo. De hecho, escribir cuidadosamente estos mensajes muestra si un programador es un buen colaborador.
Independientemente de la experiencia que tengas programando, si este tema te parece algo irrelevante es porque probablemente no le diste mucha atención a herramientas como git log. Citando al artículo que te deje antes:
“El éxito a largo plazo de un proyecto depende de su mantenibilidad y quien lo mantiene posee pocas herramientas más efectivas que el log (o registro) de su proyecto. Vale la pena tomarse el trabajo de construir uno apropiadamente. Lo que al principio puede ser algo tedioso pronto se convierte en un hábito y eventualmente en una fuente de orgullo y productividad para todos los involucrados”.
Hace poco (en febrero de 2024) conseguí mi primer trabajo IT. En una reunión con un compañero, mientras hacíamos pair programming, vió en mi pantalla cómo escribía los commits. Me dijo: “sos bastante detallado escribiéndolos”. A lo que respondí: “sí, es algo con lo que suelo insistir mucho cuando trabajo con otros. Siempre pienso que es la mejor forma de comunicarle a otros lo que está pasando en el proyecto y si un día tengo que volver al mismo, sé qué fue lo que pasó, cuándo y porqué”. Finalmente, mi compañero agrega: “Sí, es importante hacerlo. Ya me ha pasado de volver a un proyecto tiempo después, ver el log, entender poco y nada y pensar: ‘¿quién fue el idiota que escribió esto?’, para luego autoresponderme: ‘cierto, fui yo’”.
Insisto, si querés saber más sobre la importancia que tiene crear un log adecuadamente, te invito a consultar el artículo en el que este post se halla parcialmente basado. Sin más preámbulo, pasemos a lo importante: cómo escribir un mensaje de commit correctamente.
Algo que suelen decir los ingenieros (no importa la profesión o rubro) es esto: “todo depende”. Usan mucho esa palabra y es por una razón. Todo en la ingeniería es un “tradeoff”, es decir, un intercambio. Por eso el contexto determina cuándo se debería hacer cierta cosa y cuándo no. Y sea cuál sea el camino que adoptes, muy probablemente estés sacrificando algo a cambio.
Esto lo digo porque algo que llevo notando en esto llamado programación, es que pocas cosas son realmente inamovibles e inalterables. El post que ya cité como 5 veces habla de “reglas” pero también en un punto comenta que a veces las cosas dependen del equipo con el que estés trabajando y otras cuestiones. Así que más que reglas, diría que podrían llamarse “guías”, pero reglas suena mejor y más respetable (?. Me gustaría aclarar también que si bien en el artículo citado se habla de 7, decidí combinar las reglas 3 y 4 (que son parecidas) para mejorar la legibilidad de este post.
En fin, a partir de acá el post puede que se ponga un poquito denso, así que te recomiendo que, si estás apurado/a dejes la lectura acá y lo retomes en otro momento. O quizá te sirva más leer una regla por día, lo que más te convenga. Comencemos.
Primero que nada es importante tener en cuenta que no siempre hay que aplicar esto. Algunos commits solamente necesitan un asunto, es decir, una sola línea resumiendo el contenido del commit y listo. Esto es especialmente cierto cuando el cambio a introducir es muy simple y no necesita más contexto. De hecho, es lo que generalmente se hace al commitear. Ejemplo:
$ git commit -m "Fix typo in introduction to user guide"Ahora bien, cuando el commit necesita más contexto y explicación, ahí entra en juego el cuerpo o body. Mirá la diferencia del commit anterior con este otro:
Derezz the master control program
MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.La cosa cambia, ¿no? Hay varias herramientas de git relacionadas con el log que se aprovechan de esta distinción entre asunto y cuerpo, como git log, git log —oneline o git shortlog, pero ninguna funciona a menos que introduzcas una línea en blanco en el medio de ambas secciones. Así que recordá: si el commit es simple, se pone el asunto nomás. Si se necesita más detalle, hay que agregar cuerpo.
Como vimos anteriormente, a veces un commit sólo necesita una asunto y ya. Sin embargo, eso no quiere decir que se deba usar cualquiera cantidad de caracteres para escribirlo. Lo de 50 caracteres es una guía más que una regla, ya que eso puede variar (osea, depende). Lo conveniente de limitar el asunto a 50 caracteres (aproximadamente) es esto:
Es importante notar que la interfaz de GitHub tiene como límite real de 72 caracteres. Pasado dicho límite, va a cortar el mensaje de tu commit con una elipsis.
No hay mucha ciencia detrás de esto. Comenzar los asuntos con letra mayúscula mejora la legibilidad, algo que siempre es bueno considerar. Evitar ponerle un punto al final es una buena manera de ahorrar espacio, algo importante si tenemos en cuenta el límite de 50 caracteres. De modo que esto:
es mejor que esto:
Seguro habrás notado que los ejemplo que estoy dando para los commits están en inglés. Si bien es cierto que están sacados del artículo en el que este post está basado, los comparto en el idioma original ya que commitear en inglés debería ser algo a lo que te acostumbres con el tiempo.
Sé que puede ser difícil, sobre todo si estás dando tus primeros pasos en el idioma. Pero te recomiendo encarecidamente practicar escribirlos en inglés. Incluso podrías pensar un buen commit en español siguiendo estas reglas y luego usar algún traductor de confianza o pedirle a alguna IA que te haga una buena traducción.
Dicho esto, es importante usar el modo imperativo en el asunto del commit. Puede que suene extraño, pero Git usa el modo imperativo cuando crea un commit por vos. Por ejemplo, el mensaje creado por defecto al hacer un merge es algo como esto:
Merge branch 'myfeature'Si intentamos traducirlo, sería algo así como “Mergea rama ‘micaracterística’”. Pero lo importante acá es la acción. Un asunto para un commit bien formateado debería ser capaz de completar la siguiente oración:
Algunos ejemplos más:
Esto evita confusiones al transmitir el contexto. También es bueno notar que esta restricción se limita solamente al asunto. Al momento de escribir el cuerpo se puede ser más flexible.
Ojo, esto no quiere decir limitar el cuerpo a 72 caracteres, no tendría sentido. La idea del cuerpo es dar una explicación detallada del cambio y ofrecer el contexto con el mayor detalle posible. Esta regla se refiere al momento de cortar las líneas cuando escribís el cuerpo de tu commit.
Git no corta texto automáticamente, así que está bueno prestarle atención al margen derecho de lo que estás escribiendo. La recomendación de cortar el cuerpo a los 72 caracteres es para que Git tenga el espacio suficiente para indentar las líneas del cuerpo adecuadamente.
Esta regla me parece clave e intento seguirla siempre que puedo. Al momento de ofrecer contexto, es importante explicar qué es lo que estás haciendo, el cambio que estás introduciendo y la razón detrás del cambio. El cómo lo hiciste quizá no sea tan importante dependiendo del contexto y a veces ni siquiera hace falta introducirlo en el cuerpo ya que para eso están los comentarios o docstrings en el código fuente. Y si codificás siguiendo los lineamientos del clean code, todavía menos, ya que el código debería ser auto-descriptivo como regla general.
De nuevo, lo importante es dejar bien claras las razones de porqué hiciste el cambio en primer lugar, la forma en que funcionaba todo antes y lo que estaba mal con eso, la forma en que funciona ahora y porqué decidiste resolverlo de la forma en que lo hiciste.
Ofrecer contexto mediante los mensajes que acompañan a nuestros commits es una gran forma de demostrar que somos personas colaborativas, un gran rasgo a cultivar para ser buenos/as programadores/ras. No sólo se benefician tus compañeros/ras, sino que incluso puede representar un beneficio para tu futuro yo cuando sea momento de volver al proyecto pasado un buen tiempo.
Recordá tener presente las reglas para escribir el asunto y el cuerpo, y la importancia de explicar el qué y el porqué antes que el cómo.
Ahora bien, incluso siguiendo estos lineamientos, puede pasar que cada uno en un equipo desarrolle su propia forma de escribir los commits. ¿Hay alguna manera de solventar esas potenciales diferencias y lograr construir un registro (log) consistente entre todos los miembros del equipo? Si, los commits convencionales. Pero esa es una historia para otro momento 😉
Python / ETL dev | Data Engineer en progreso | Musico | Nerd de yerbas varias