¿Cuál es el nivel de detalle apropiado para las notas de logging?

Cuando ingreso el código, alguna vez escribo notas de logging muy largas y detalladas, otras escribo las más breves (o ninguna nota). Las notas más largas tienden a include información sobre por qué se realizó el cambio (motivos comerciales, interacciones con los clientes, etc.). Sin embargo, no estoy seguro si las notas de logging son el lugar correcto para tal detalle. La mayoría de las notas de check-in que he visto tienden a ser cortas y simplemente hacen reference a un error.

¿Cuál es el nivel de detalle apropiado para las notas de logging?

La respuesta correcta, he encontrado, depende de las necesidades de su organización. Suena difuso, pero la razón principal para proporcionar detalles para un check-in de código es para el context y la comprensión si ese check-in necesita ser revisado o revisitado. Puede ser increíblemente detallado, o puede ser notablemente simple.

En una compañía, nuestros check-ins de código harían reference a # + ticket-number. Esto correlacionó nuestros compromisos de SVN con un número de ticket de Trac , que contenía todos nuestros detalles sobre un tema o function determinada que estábamos implementando. Hicimos reference a todo a través de Trac, por lo que mantener nuestros detalles en esa forma funcionó mejor para nosotros.

Para ti, depende de cómo trabajen tú y tu equipo. Basaría la información que guarda en sus loggings sobre la necesidad de los datos, la frecuencia con la que se hace reference a los mismos y qué sucede si pierde el context (es decir, no tiene idea de por qué se implementó un cambio).

Otra consideración puede ser acceder a esas notas fuera de su depósito de código, que puede no ser el mecanismo más efectivo para almacenar esa información. No obstante, creo que es una preference personal.

Lo que su gerente o la documentation de la empresa le indique;)

Dicho esto, más corto es mejor. No es la herramienta correcta para una documentation larga: el software de seguimiento de errores / funciones está diseñado para esto y, en la mayoría de los casos, puede integrarse con el control de origen.

Solo lo suficiente, al seguir el logging unas semanas más tarde para tener una idea de lo que sucedió.

Utilizo estos loggings para verificar lo que se ha hecho en el último día (o días) en el proyecto que estoy llevando a cabo.

Los posts más cortos no necesariamente significan mejor. Ni posts más largos. Solo tenga en count el objective de esos comentarios: ofrecer una descripción general de la actividad en el sistema de control de versiones.

En mi experiencia de control de versiones, tiendo a maldecir a los que no dejaron ninguna nota, o una nota que tarda 5 minutos en abrirse paso.

Si usa su sistema de control de versiones para explorar el historial de un file y encontrar un cambio específico, es mejor include un breve comentario sobre el por qué y el qué. El cómo ir en la documentation del código fuente.

Cada vez que escribo un comentario o un post de logging de compromiso me pregunto "¿qué va a necesitar saber el próximo chico? ¿De qué me van a preguntar?"

Responder a una pregunta parece ser la manera más fácil de mantener los comentarios breves y útiles. También evita la anti-documentation (reformulando el código, a menudo de manera involuntariamente irónica) o reformulando los metadatos que los vcs seguirán de todos modos (se agregó foo.java, cambio de martes, nueva label "bar-1-1-4")