Intentando hacer buenos commits

Se ha solucionado ya el bug del ticket #1234. Es una frase que puedes oír perfectamente en el trabajo. El ticket afecta a parte una parte del sistema que tú conoces muy bien y te piden revisar el arreglo. Así que ni corto ni perezoso te poner a ver las historias de las revisiones y vez que hay 4 subidas con mensajes como “ajustar DAO”, “soluciones”, “eliminar depuración”. Empiezas a temblar e innumerables blasfemias recorren tu mente… Una solución que no sería más de 3 líneas de código se ha convertido en un puñado de líneas de código y  una revisión de 2 puñados de archivos.

Un control de versiones es algo más que una pila desordenada de copias de seguridad. Así que en este artículo vamos a dar una serie de consejillos sobre mantener un repositorio útil.

Sólo 1 cambio por commit

Imagina que te asignan 2 tickets para resolver #1234 y el #4567, para solucionarlos hay que cambiar unas cosillas como pueden ser añadir 2 botones a la interfaz, refactorizar dos clases y cambiar unos tabuladores. Entonces corriges el bug #1234 y resuelves #4567.

¿Qué pasa si una semana más tarde hay un error aun peor debido a bug #1234? No podemos hacer revert (git) o backout (Hg) porque cambiarás demasiadas cosas que sí funcionan, es decir, estas tirando a la basura cambios que si son correctos.

La solución es hacer un cambio en cada commit. Por tanto en los comentarios del commit olvídate de “y” — > Realizado XXXX y ZZZZ

Quizás pensarás que hay veces que al abrir un archivo se te ocurren 100 ideas sobre cómo mejorarlo (refactorizar, investigar sobre funciones que mejoren tu código…) Apunta estas tareas como TODO, pero haz un solo cambio por commit.

De acuerdo, hay veces en los que no hay manera de terminar el ticket #1234 sin antes hacer algún otro cambio. Así que si usas Git, la forma más fácil de separar estos cambios es con stash (Git) o shelve (HG).

Hacer todo el cambio en un commit

Un cambio es difícil de revisar y deshacer si se distribuye en varias entregas. Esto a veces puede ser un efecto secundario de trabajar en varias cosas a la vez. Por ello concentrarse en una tarea cada vez es crucial.

Aunque bien es cierto, que muchos cambios son tan grandes que deshacerlos del todo puede ser imposible, por eso es necesario a veces guardar versiones del trabajo en curso. Para poder guardar versiones WIP (Work in progress) podemos utilizar rebase (git) o histedit (Hg) para desplegar los cambios de una sola vez cuando se haya terminado.

Otra manera de hacerlo es utilizar el índice de Git para tener un quicksave de las versiones WIP.

Documentar los cambios

Si escribimos un mensaje de commit “Correcciones” <vámonos>>. Si alguien necesita ver el historial de versiones, mensajes como este hacen que tenga que leer todo el código y viendo lo que ha cambiado.

Un buen mensaje (son difíciles de hacer) le dice a la persona que lee, que parte del código ha cambiado y cómo, todo ello sin mirar el código.

Por ejemplo:  MiClase:: usa abcd en lugar de xyzw en el métodomiMetodo( ver #1234)

Documentar por qué se realizó ese cambio

Es importante documentar por qué se realiza cada cambio. Esto impide refactorizar código, así si otro desarrollador ve ese código sino porque, asume que está así por una “buena razón” y lo  mejor no lo toca.

Si se cambia algo hay que documentarlo, por ejemplo: miMetodo( tuyu)// tyuyu está ordenado así que es mejor utilizar abcd en lugar de cyzw

Obviamente, si el código es obvio, lo mejor es no es necesario poner //hacemos un bucle

Lo mejor es siempre apoyarse en el número del ticket para conocer el contexto del cambio.

No hacer commit de código comentado

Sí, todos lo  hacemos, dejar código comentado “por si acaso” es necesario en el futuro.

¿Por qué el código comentado? ¿Funciona? ¿El código que ha sido comentado es peor? Al final solo conseguimos distraer del código que se está utilizando.

Conclusiones

Creo que hay que seguir una serie de reglas para hacer un commit, pero no es tanto seguirlas a rajatabla, como que intentar que todo el equipo siga las mismas, porqué así será más fácil mantener el código.

Aunque creo que lo más fácil es seguir estas 2 reglas:

Regla # 1: escribir comentarios commits antes de codificar
Regla # 2: escribir lo que el software debe hacer, no lo que hiciste

Y llegados  aquí, este post es una traducción libre de aquí http://dev.solita.fi/2013/07/04/whats-in-a-good-commit.html

Más info aquí: http://arialdomartini.wordpress.com/2012/09/03/pre-emptive-commit-comments/

Y si te gustan los mensajes de commit, creo que deberías utilizar esto: http://whatthecommit.com/