Cómo escribir comentarios en commits

Prefacio del traductor

A lo largo de los años de desarrollo de software, siendo miembro de muchos equipos, trabajando con varias personas buenas y experimentadas, a menudo observé (y para ser sincero, creé) el mismo problema: un desastre total en el repositorio. Cada uno escribió comentarios sobre commits en su propio estilo (y bueno, si constantemente en uno); la mitad de los comentarios fueron inútiles (de la categoría " esto es un puente "), la mitad de la mitad restante apenas se entendió.

Y luego, un buen momento, vi este artículo, antes de lo cual finalmente pude tener en mis manos la traducción. Solo 7 reglas simples y cortas, y he aquí, mirar la historia de los commits no solo fue útil, sino también agradable. Nada revolucionario, todo es bastante obvio, pero formulado y resumido perfectamente.

Quiero señalar que este es un artículo de 2014. Algunas cosas poco relevantes mencionadas por el autor podrían perder relevancia, pero la esencia del artículo no lo es en absoluto.

Introducción: por qué los buenos comentarios son importantes

Si busca en un repositorio aleatorio de Git, lo más probable es que encuentre algún tipo de desorden en el historial de confirmación. Por ejemplo, eche un vistazo a estas perlas desde el momento en que comencé a comprometerme con el repositorio de Spring:

 $ git log --en línea -5 - vigas de autor - antes del "vie 26 de marzo de 2009"

 e5f4b49 Vuelva a agregar ConfigurationPostProcessorTests después de su breve eliminación en r814.  @ Ignorando el método testCglibClassesAreLoadedJustInTimeForEnhancement () ya que resulta que este fue uno de los culpables de la reciente ruptura de compilación.  El pirateo del cargador de clases provoca sutiles efectos posteriores, rompiendo pruebas no relacionadas.  El método de prueba sigue siendo útil, pero solo debe ejecutarse de forma manual para garantizar que CGLIB no se cargue prematuramente en clase, y no debe ejecutarse como parte de la compilación automatizada.
 2db0f12 solucionó dos problemas de ruptura de compilación: + revertió ClassMetadataReadingVisitor a la revisión 794 + eliminó ConfigurationPostProcessorTests hasta que una investigación más profunda determine por qué hace que las pruebas posteriores fallen (como las aparentemente no relacionadas ClassPathXmlApplicationContextTests)
 147709f Ajustes a los archivos package-info.java
 22b25e0 Consolidated Util y MutableAnnotationUtils clases en AsmUtils existentes
 7f96f57 pulido

Horror Compare con estas confirmaciones más recientes en el mismo repositorio:

 $ git log --en línea -5 - autor pwebb --antes del "sábado 30 de agosto de 2014"

 5ba3db6 Solucionar errores de CompositePropertySourceTests
 84564a0 Rework @PropertySource lógica de análisis temprano
 e142fd1 Agregar pruebas para metadatos ImportSelector
 887815f Actualiza la dependencia de docbook y genera epub
 Uso de mockito polaco ac8326d

¿Qué opción preferirías?

Los primeros varían en longitud y estilo, los segundos son concisos y homogéneos.
El primero se obtiene por sí mismo, el segundo se escribe conscientemente.

Y aunque el historial de confirmación de muchos repositorios parece la primera opción, hay excepciones. Grandes ejemplos son el kernel de Linux y el propio Git . Eche un vistazo a Spring Boot o cualquier otro repositorio con el que se ocupe Tim Pope .

Los participantes en estos proyectos saben que un comentario bien escrito sobre el compromiso es la mejor manera de contar el contexto de los cambios realizados a otros desarrolladores (así como a ellos mismos en el futuro). Las diferencias en las revisiones muestran lo que ha cambiado, pero solo un comentario puede explicar claramente por qué . Peter Hutterer lo dijo bien :

Recuperarse de la codificación es una pérdida de tiempo. No podemos evitarlo por completo, por lo que nuestros esfuerzos deberían centrarse en minimizar estos costos. Para eso están los comentarios sobre commits. Por lo tanto, muestran si el programador funciona bien en un equipo.

Si realmente no ha pensado qué debería ser un comentario de confirmación de primer nivel, probablemente no haya utilizado git log y herramientas similares con demasiada frecuencia. Hay un círculo vicioso: dado que la historia de los commits no está estructurada y es heterogénea, no la usan ni prestan atención. Y debido al hecho de que no lo usan y no prestan atención, sigue siendo desestructurado y heterogéneo.

Pero una historia de repositorio bien diseñada es algo hermoso y útil. Los comandos culpan , revierten , rebase , registran , abrevian y otros cobran vida . Tiene sentido mirar los compromisos y solicitudes de extracción de otras personas, y, de repente, ahora ya no se necesita la ayuda de sus autores. Para comprender por qué sucedió algo [en el código] hace meses o años, no solo es posible, sino también conveniente.

El éxito a largo plazo del proyecto depende (entre otras cosas) de lo conveniente que sea mantenerlo, y el historial de confirmaciones es una de las herramientas más poderosas del responsable del mantenimiento. Vale la pena pasar tiempo aprendiendo cómo mantener el orden. Al principio, esto puede causar algunos inconvenientes, pero luego se convertirá en un hábito y, al final, se convertirá en una fuente de orgullo y trabajo productivo para todos los participantes.

Este artículo solo toca el componente más básico para mantener una buena historia, a saber, cómo escribir un comentario en una confirmación por separado. Hay otras cosas importantes, como la fusión de compromisos que no se tratan aquí.

La mayoría de los lenguajes de programación tienen convenciones generalmente aceptadas bien descritas que forman un estilo distintivo [de escribir código], como nombres de variables, reglas de formato, etc. Por supuesto, existen diferentes versiones de dichos acuerdos, pero la mayoría de los desarrolladores opinan que elegir una opción y seguirla es mucho mejor que un desastre cuando cada uno escribe con su propio estilo.

El enfoque del equipo para describir las confirmaciones debe ser exactamente el mismo. Para que la historia del repositorio sea útil, el equipo debe llegar a un acuerdo sobre al menos los siguientes tres puntos.

Estilo. Sintaxis de marcado, sangría, saltos de línea, gramática, letras mayúsculas, puntuación. Siempre revisa tu ortografía y escribe lo más fácil posible. Como resultado, obtendrá un historial sorprendentemente completo de confirmaciones, que no solo es agradable de leer, sino que realmente leerá regularmente.

Contenido ¿Qué información debe (si es que debe) estar contenida en el cuerpo del comentario? ¿Por qué no debería estar allí?

Metadatos ¿Cómo debo referirme a ID de tareas, números de solicitud de extracción, etc.?

Afortunadamente, ya hay acuerdos para escribir un comentario significativo. De hecho, se derivan parcialmente de la forma en que funcionan algunos comandos de Git. No es necesario reinventar la rueda. Simplemente siga las siete reglas a continuación, y estará un paso más cerca de la historia de los compromisos dignos de un profesional.

Siete reglas para un comentario de confirmación genial

Recuerde: Todo esto se ha dicho antes .

1. Separe el encabezado del cuerpo con una cadena vacía
2. Limite el título a 50 caracteres.
3. Capitalizar el titular
4. No ponga un punto al final del título.
5. Usa el imperativo en el título.
6. Ir a la siguiente línea del cuerpo con 72 caracteres.
7. En el cuerpo, responda las preguntas de qué y por qué , y no cómo

Por ejemplo:

 Resumir los cambios en 50 caracteres o menos.

 Aquí explíquelos con más detalle, si es necesario.  Seguimiento
 saltos de línea de aproximadamente 72 caracteres.  En algunas situaciones
 la primera línea del comentario se considera su título, y todos 
 el resto es con el cuerpo.  Es imperativo separar para separar uno del otro
 una cadena vacía (si el mensaje tiene un cuerpo, por supuesto);
 varias herramientas como `log`,` shortlog` y `rebase` no entenderán
 si el encabezado y el cuerpo no están separados.

 Explica aquí qué problema resuelve este commit.  Llevar 
 más atención a por qué hizo estos cambios, no a 
 exactamente cómo lo hizo (esto le explicará el código).
 ¿Hay efectos secundarios u otros efectos no obvios en 
 estos cambios?  Si es así, esto debe explicarse aquí.

 Los párrafos están separados por líneas en blanco.

  - Puedes hacer listas con viñetas

  - Por lo general, un asterisco o 
    Un guión con un espacio delante de ellos.  pero hay diferentes acuerdos

 Si tiene un rastreador de errores [o un sistema de gestión de proyectos],
 coloque enlaces de tareas al final del texto de esta manera:

 Resuelto: # 123
 Ver también: # 456, # 789

1. Separe el encabezado del cuerpo con una cadena vacía

Del manual al comando git commit :

Aunque esto no es necesario, es una buena idea comenzar un comentario sobre la confirmación con una línea corta (menos de 50 caracteres) que resuma los cambios realizados, luego una línea vacía y luego una descripción más detallada. El texto antes de la primera línea vacía en el comentario se considera el encabezado de la confirmación y se usa en diferentes comandos de Git. Por ejemplo, Git-format-patch (1) convierte una confirmación en correo electrónico; el equipo usa el encabezado del commit para el tema de la carta y el resto del texto para el cuerpo de la carta.

En primer lugar, no todas las confirmaciones requieren un encabezado y un cuerpo. A veces, una línea es suficiente, especialmente cuando los cambios son tan pequeños que no se requiere información adicional sobre ellos. Por ejemplo:

  Reparar error tipográfico en la introducción a la guía del usuario 

Suficiente dicho; Si el usuario quiere saber qué tipo de error ha sido corregido, puede ver los cambios por sí mismo usando git show o git diff , o git log -p .

Si confirma algo así usando la línea de comando, será conveniente usar la opción -m para git commit :

  $ git commit -m "Arreglar error tipográfico en la introducción a la guía del usuario" 

Sin embargo, cuando el commit merece alguna explicación y descripción de la situación, debe escribirlos en el cuerpo del comentario. Por ejemplo:

 Derezz el programa de control maestro

 MCP resultó ser malvado y se había empeñado en dominar el mundo.
 Este commit arroja el disco de Tron a MCP (causando su desresolución)
 y lo convierte de nuevo en un juego de ajedrez.

Los comentarios que tienen un cuerpo no son tan convenientes para escribir con la opción -m . Sería mejor usar un editor de texto para esto. Si aún no ha configurado el editor para usarlo con Git, lea esta sección del libro Pro Git .

En cualquier caso, la separación del título y el cuerpo del comentario dará sus frutos al ver el registro. Aquí está el registro de confirmación completo:

 $ git log
 commit 42e769bdf4894310333942ffc5a15151222a87be
 Autor: Kevin Flynn <kevin@flynnsarcade.com>
 Fecha: Vie Ene 01 00:00:00 1982 -0200

  Derezz el programa de control maestro

  MCP resultó ser malvado y se había empeñado en dominar el mundo.
  Este commit arroja el disco de Tron a MCP (causando su desresolución)
  y lo convierte de nuevo en un juego de ajedrez.

Y aquí está el comando git log --oneline , que solo muestra la línea de encabezado:

 $ git log --en línea
 42e769 Derezz el programa de control maestro

O git shortlog, que agrupa los compromisos por autor, nuevamente, por brevedad, solo muestra el título:

 $ git shortlog
 Kevin Flynn (1):
       Derezz el programa de control maestro

 Alan Bradley (1):
       Introducir el programa de seguridad "Tron"

 Ed Dillinger (3):
       Cambiar el nombre del programa de ajedrez a "MCP"
       Modificar programa de ajedrez
       Actualizar el programa de ajedrez

 Walter Gibbs (1):
       Introducir el programa de ajedrez prototipo

Hay muchas otras situaciones en las que es necesario distinguir entre el encabezado y el cuerpo del commit, y para esto deben estar separados por una línea vacía.

2. Limite el título a 50 caracteres.

Técnicamente, es posible ir más allá de 50 caracteres, pero no se recomienda. Esta extensión del título garantiza su legibilidad y también hace que el autor piense en la redacción más concisa y clara para describir lo que está sucediendo.

Sugerencia: si le resulta difícil resumir los resultados del trabajo, tal vez una confirmación contenga demasiados cambios. Esfuércese por hacer confirmaciones atómicas (este es un tema para una publicación separada).

La interfaz de GitHub claramente admite estas convenciones. Te avisará si superas el límite de 50 caracteres:


Y corte todos los encabezados de más de 72 caracteres, sustituyendo una elipse:


Así que apunta a 50 caracteres, pero ten en cuenta que 72 es una restricción estricta.

3. Capitaliza el título

Todo es simple aquí. Capitalizar todos los encabezados.

Por ejemplo:

• Acelera a 88 millas por hora

En cambio:

• acelerar a 88 millas por hora

4. No ponga un punto al final del título.

No hay necesidad de eso. Además, cada personaje cuenta cuando tratamos de cumplir 50.

Por ejemplo:

• Abra las puertas de la bahía de pod

En cambio:

• Abra las puertas de la bahía de la vaina.

5. Usa el imperativo en el título.

El estado de ánimo imperativo significa literalmente: una forma de un verbo que expresa una voluntad (orden, solicitud o consejo). Algunos ejemplos

• Limpia tu habitación (ordena la habitación)
• Cierra la puerta
• Sacar la basura

Cada una de las siete reglas sobre las que está leyendo está escrita en el estado de ánimo imperativo ("Vaya a la siguiente línea del cuerpo con 72 caracteres", etc.).

Esta forma puede sonar un poco grosera y, por lo tanto, no se usa con tanta frecuencia [en inglés - aprox. trans. ] Pero es perfecto para el encabezado de confirmación. Una razón es el hecho de que Git usa el imperativo cuando se compromete en su nombre.
Por ejemplo, cuando se usa git merge, el siguiente mensaje se agregará de manera predeterminada:

 Fusionar rama 'myfeature'

Y cuando se usa git revert :

 Revertir "Agregar la cosa con las cosas"
	
 Esto revierte commit cc87791524aedd593cff5a74532befe7ab69ce9d.

O cuando hace clic en el botón "Combinar" en la interfaz de solicitud de extracción en GitHub:

 Solicitud de extracción de fusión # 123 de someuser / somebranch

Entonces, cuando escribes tus propios mensajes de confirmación en el estado de ánimo imperativo, sigues las reglas establecidas en Git. Por ejemplo:

• Refactorizar el subsistema X para facilitar la lectura
• Actualizar la documentación de inicio
• Eliminar métodos obsoletos
• Versión de lanzamiento 1.0.0

Al principio, este método puede parecer incómodo. Estamos más acostumbrados a usar el indicativo, que es más probable que informe hechos. Por lo tanto, los mensajes de confirmación suelen ser algo como esto:

• Error corregido con Y
• Cambio de comportamiento de X

Y a veces los encabezados simplemente describen el contenido de la confirmación:

• Más soluciones para cosas rotas
• Dulces nuevos métodos API

Hay una regla simple que le permitirá evitar errores.

Un encabezado de confirmación correctamente compuesto debe completar la siguiente oración:

• Si se aplica, este commit < commit header >

Por ejemplo:

• Si se aplica, esta confirmación refactorizará el subsistema X para facilitar la lectura
• Si se aplica, esta confirmación actualizará la documentación de inicio
• Si se aplica, esta confirmación eliminará los métodos obsoletos
• Si se aplica, esta confirmación lanzará la versión 1.0.0

Si se aplica, esta confirmación combinará la solicitud de extracción # 123 del usuario / sucursal

Asegúrese de que los verbos en otros estados de ánimo no imperativos no funcionen aquí:

• Si se aplica, esta confirmación solucionará el error con Y
• Si se aplica, esta confirmación cambiará el comportamiento de X
• Si se aplica, este commit tendrá más correcciones para cosas rotas
• Si se aplica, esta confirmación endulzará nuevos métodos API

Recuerde: usar el imperativo es importante solo en el encabezado de la confirmación. En el cuerpo del commit, esto es opcional.

6. Ir a la siguiente línea del cuerpo con 72 caracteres.

Git en sí no organiza saltos de línea automáticamente. Al editar el cuerpo del comentario, debe recordar el borde derecho y establecer saltos de línea manualmente.

Se recomienda que pase a la siguiente línea con 72 caracteres para que Git pueda sangrar y que quepa 80 caracteres en total.

Un buen editor de texto puede ayudar con esto. Es bastante fácil configurar, digamos, Vim, para alimentar 72 caracteres para escribir un mensaje en una confirmación. Sin embargo, sucedió que los IDE son terriblemente pobres para admitir saltos de línea inteligentes para confirmaciones de mensajes (aunque las últimas versiones de IntelliJ IDEA finalmente han mejorado en esta parte). ( aprox. por. - quizás en este momento todo está mucho mejor ).

7. En el cuerpo, conteste las preguntas "qué" y "por qué", no "cómo"

Este compromiso del repositorio de Bitcoin proporciona una excelente explicación de qué y por qué ha cambiado:

 commit eb0b56b19017ab5c16c745e6da39c53126924ed6
 Autor: Pieter Wuille <pieter.wuille@gmail.com>
 Fecha: viernes 1 de agosto 22:57:55 2014 +0200

    Simplifique el manejo de excepciones de serialize.h

    Elimine el 'estado' y 'exceptmask' de la secuencia de serialize.h
    implementaciones, así como métodos relacionados.

    Como la máscara de excepción siempre incluía 'failbit', y setstate siempre era
    llamado con bits = failbit, todo lo que hizo fue levantar inmediatamente un
    excepción  Deshazte de esas variables y reemplaza el setstate
    con lanzamiento directo de excepciones (que también elimina algunos muertos
    código).

    Como resultado, bueno () nunca se alcanza después de una falla (hay
    solo 2 llamadas, una de las cuales está en pruebas), y solo se puede reemplazar
    por! eof ().

    fail (), clear (n) y excepciones () simplemente nunca se llaman.  Eliminar
    ellos.

Mire los cambios en el código y piense cuánto tiempo ahorró el autor a los participantes presentes y futuros del proyecto, describiendo el contexto del trabajo realizado en el comentario. De lo contrario, probablemente estaría perdido para siempre.

En la mayoría de los casos, puede omitir los detalles de cómo se realizaron los cambios. Por lo general, el código habla por sí mismo en este sentido (y si es tan complejo que se requiere una aclaración, entonces hay comentarios al respecto).

Concéntrese principalmente en explicar por qué se hicieron los cambios: describa la situación antes de que se hiciera el cambio (y qué estaba mal), la situación posterior y por qué eligió esta forma particular de resolver el problema.

¡Quizás en el futuro te lo agradecerás!

Consejos

Me encanta la línea de comando. Olvidado sobre el IDE.

Hay muchas razones, por la cantidad de comandos Git, para usar la línea de comandos al máximo. Git es una herramienta increíblemente poderosa; IDE - también, pero cada uno a su manera. Uso IntelliJ IDEA todos los días, a menudo tuve que tratar con otros (por ejemplo, Eclipse), pero nunca vi que la integración de Git en el IDE pudiera compararse en simplicidad y capacidades con la línea de comando (tan pronto como lo entiendas).

Ciertas características del IDE para el control de versiones son simplemente invaluables, por ejemplo, ejecutar automáticamente git rm cuando elimina un archivo u otras piezas necesarias de git cuando lo renombra. Pero es mucho peor cuando intentas comprometer, fusionar, modificar o hacer un análisis complejo del historial de confirmaciones usando el IDE.

Cuando necesita desbloquear todo el potencial de Git, la línea de comando es insuperable.
Recuerde que si usa Bash, Zsh o Powershell, hay scripts para completar comandos que lo salvan de la dolorosa necesidad de recordar todos los subcomandos y opciones.

Lee el libro Pro Git

El magnífico libro Pro Git ( también en ruso - aprox. Traducción ) está disponible gratuitamente. ¡Aprovecha esto!