Mensajes de confirmación adecuada

¿Para qué son los mensajes de confirmación? Siempre los he estado escribiendo como una explicación de lo que hice, pero recientemente comencé una discusión al respecto con un colega que escribe mensajes de compromiso explicando por qué lo hizo. ¿Cuál es el correcto o hay otra respuesta por completo?Mensajes de confirmación adecuada

NOTA: No tengo ni idea de si hay una respuesta "correcta" para esto. Como tal, lo he etiquetado wiki de la comunidad y no aceptaré una respuesta. Los votos ascendentes decidirán el ganador :)

Fuente

2010-06-10 Clark Gaebel

Como preferencia personal, puedo decir que se hizo al observar las diferencias en los archivos directamente. El por qué es lo que no puedo deducir simplemente mirando los cambios reales.

Si los cambios son significativos o complicados, entonces incluiría no solo el por qué, sino también una breve descripción de cómo.

Fuente

2010-06-10 03:40:48

Veo un mensaje de confirmación como un correo electrónico. El "qué" es el asunto, tal vez haciendo referencia a un error #, pero debe describir brevemente el cambio El cuerpo del mensaje de compromiso es el por qué. –

En realidad, mirar el diff le dice * cómo * se hizo, los comentarios en el código y el sistema de seguimiento de problemas deberían decirle * por qué *, y el mensaje de confirmación debería decirle * qué *, preferiblemente junto con un enlace a el sistema de seguimiento de problemas. en mi opinión, por supuesto. –

Algunos cambios no se envían fácilmente a "comentarios ... debería decirle por qué": borrar código podrido, por ejemplo. Agregar el "por qué" a los comentarios cada vez podría terminar en un escenario de SCM en código fuente. De acuerdo, a veces * tiene * sentido agregar un comentario explicando por qué el enfoque "obvio" de agregar algún código aquí sería incorrecto. –

Creo que ambos son útiles. Una descripción rápida de lo que cambió ("Agregar validación de longitud para AddUserForm") es más fácil que mirar un diff, especialmente si está navegando en múltiples commits. Por qué se realizó el cambio, qué error solucionó, etc. obviamente también es algo muy bueno de tener.

Fuente

2010-06-10 03:45:35

uso el mensaje de confirmación como un executive summary de lo que fue cambiado.

Resumen ejecutivo [...] es un breve documento que resume [...] de forma tal que los lectores pueden familiarizarse rápidamente con una gran cantidad de material sin tener que leerlo todo.

El qué está documentado en otro lugar: un sistema de seguimiento de problemas, requisitos de documentación, etc. También se incluyen enlaces desde el mensaje de confirmación a la por qué, y viceversa.

Fuente

2010-06-10 03:46:03 Dolph

¿Por qué es importante? Si no lo está documentando en otro lugar, póngalo en el mensaje de confirmación. –

@theatrus, estoy absolutamente de acuerdo, pero para cualquier proyecto mediano-grande, los mensajes de compromiso son ** no ** el lugar para documentar * por qué. – Dolph

@Dolph, creo que los mensajes de confirmación son un * gran * lugar para poner código-por qué, pero estoy de acuerdo contigo en que es un mal lugar para poner proyectos por qué. Ejemplo: "Este código estaba rompiendo foo porque segfaulted en la barra": bueno. "Esta característica es necesaria para apoyar a Joe de Foo Inc.": mala. –

Los mensajes de confirmación son lo que usted hace de ellos, pero cuando hay cientos de ellos para un archivo en particular, o miles para un proyecto, desea poder escanearlos buscando ciertos cambios o la naturaleza de los cambios . En efecto, son como comentarios de código, y deben ser lo más útiles posible, pero concisos y concisos. Tal vez sea mejor pensar en ellos como tweets: transmitir el máximo significado en un espacio corto.

Como alguien que ha trabajado en grandes bases de código que abarcan décadas, y también proyectos más pequeños que abarcan uno o dos años, no he encontrado nada más irritante al peinarse cometer registros de mensajes como "vaya" o "Solución de error". Si corrigió un error, díganos cuál (un número de error, como mínimo). Todo es importante para los inevitables análisis forenses en el futuro.

Fuente

2010-06-10 03:50:23 brainjam

Respuesta

Cuestiones relacionadas