¿Es buena idea poner números de error en un comentario al comienzo del archivo fuente? [cerrado]

¿Es una buena práctica poner números de error en el archivo dentro de un comentario de encabezado?

Los comentarios se verían así:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Parece útil, pero ¿se considera una mala práctica?

He visto esto antes, tanto de forma manual por autores como automáticamente por scripts y disparadores integrados con sistemas de control de versiones para agregar autor, comentarios de registro e información de fecha al archivo.

Creo que ambos métodos son bastante terribles por dos razones principales. Primero, agrega desorden y ruido al archivo, especialmente a medida que estos comentarios envejecen y se vuelven irrelevantes para el estado actual del archivo. En segundo lugar, es información duplicada de lo que ya se mantiene en el sistema de control de versiones, y si está utilizando un sistema de control de versiones moderno que admite conjuntos de cambios, en realidad está perdiendo información sobre los cambios.

En todo caso, considere la integración con su sistema de seguimiento de defectos. Algunas herramientas le permiten vincular un defecto o número de ID de tarea en un comentario de check-in a un elemento en la herramienta de seguimiento. Si tiene todos sus defectos, solicitudes de mejora y tareas de trabajo en la herramienta, puede proporcionar enlaces de esa manera. Por supuesto, esto viene con la desventaja de una dependencia de esas herramientas para el proyecto.

Hay exactamente un caso en el que haría esto, es decir, como parte de una advertencia para futuros programadores: "No llame a la función foo()aquí directamente; esto ha provocado el error # 1234, a saber ...", y luego una breve descripción del error sigue.

Y si el código ha cambiado de manera que no haya tentación de llamar foo()directamente, elimine ese comentario. Solo irritaría y explotaría el código.

Es una práctica totalmente horrible. Agrega esfuerzo para lograr un efecto que es pura duplicación; en otras palabras, lo único que agrega sobre el uso de registros de confirmación es la posibilidad de crear inconsistencias. Sus archivos de origen se llenan de cantidades ilimitadas de cosas que nunca mira.

Lo único positivo que puedo discernir es que podría reconstruir el historial de origen sin acceso al control de versión, por ejemplo, al estudiar una impresión. Pero muy pocas personas son lo suficientemente competentes como para seguir las complejidades del desarrollo de software, a la vez que no pueden comprender el control de versiones.

No.

Eso es lo que la gente hacía antes de usar un sistema de control de versiones (es decir, cuando el código fuente era solo copias de seguridad en archivos zip).

Es, en mi humilde opinión, una muy mala idea. Después de la revisión número 100, tendrá 90% de comentarios y 10% de código. No lo consideraría tan limpio y legible.

El único punto en esto que veo es cuando tiene que intercambiar su código entre SCC y, por cualquier razón, no puede transferir el historial entre los dos sistemas (pero incluso cuando guarda los comentarios del historial de esa manera, perderá el historial de diferencias también, por lo que guardar los comentarios solo te ayudará un poco).

Veo que todos se oponen a la idea y dieron una razón histórica (era de control previa a la fuente) de por qué la gente lo estaba haciendo.

Sin embargo, en mi empresa actual, los desarrolladores de bases de datos siguen esta práctica y además etiquetan el número de error alrededor del código. A veces me parece útil cuando ve un error en el código y puede descubrir instantáneamente la corrección del error que introdujo este problema. Si no tenemos esa información en mi paquete de base de datos, ciertamente no será fácil encontrar la causa raíz de esa implementación.

Sí, satura el código, pero ayuda a encontrar la razón de por qué ese código está allí.

Uno de los puntos en la prueba de Joel es

¿Tienes una base de datos de errores?

Dicha información podría guardarse en una base de datos de errores si cree que son importantes, pero solo serían ruido en los comentarios.

Creo que tienes dos problemas aquí. Primero, ¿por qué debería confiar únicamente en el diff cuando la mayoría de los sistemas le permiten ingresar comentarios de revisión? Al igual que los buenos comentarios de código, descubres por qué se realizó el cambio y no solo el cambio en sí.

En segundo lugar, si tiene esta capacidad, conviene colocarlos todos en el mismo lugar. No es necesario buscar en el archivo líneas de código marcadas que ya no se necesitan. Los comentarios dentro del código de trabajo están ahí para decirle por qué está codificado de esta manera.

Una vez que pone esto en práctica, los hábitos formados hacen que la base del código sea más fácil de trabajar para todos.

El seguimiento asociado de errores y funciones, junto con el motivo por el que está cambiando este archivo, puede darle una idea de qué tan profundo necesita profundizar en el historial y posiblemente mirar las diferencias. Tenía una solicitud para "Cambiar de nuevo a la fórmula original". Sabía exactamente a dónde ir dentro del historial de revisiones y solo revisé una o dos diferencias.

Personalmente, el código remarcado parece un trabajo en progreso para un problema que se resuelve mediante prueba y error. Elimina este desastre del código de producción. Poder deslizar fácilmente líneas de código dentro y fuera solo hace que sea más fácil confundirse.

Si no tiene VCS con mensajes de confirmación, y no tiene un sistema de seguimiento de errores con una opción para dejar comentarios, es una opción, y no la óptima, para realizar un seguimiento de los cambios.
Es mejor tener una hoja de cálculo con esa información, o si se encuentra en un entorno sin tales "lujos", un archivo de texto ubicado en algún lugar cerca de sus fuentes.
Pero recomiendo encarecidamente que si se encuentra en ese entorno, comience a construir un caso para invertir en un VCS y un sistema de seguimiento de errores :)

Tenga esto en cuenta: el código suele ser más largo que las herramientas que lo admiten. Dicho de otra manera, los rastreadores de problemas, el control de versiones y todos los demás scripts evolucionarán a lo largo del desarrollo. La información se pierde.

Si bien estoy de acuerdo, el desorden de archivos es molesto, abrir un archivo y comprender su historial sin recurrir al uso de las herramientas siempre ha sido muy útil, especialmente si mantengo el código.

Personalmente, creo que hay espacio tanto para las herramientas como para el registro en código.

Sé Git no hace esto y la respuesta simple es "¿por qué tendría que ir allí?"

Es un diseño menos modular en general. Bajo esta solución, ahora los archivos son una mezcla entre contenido y metadatos. Amazon S3 es otro ejemplo de un servicio para almacenar archivos que no agrega elementos frontales de YAML o similares a los archivos.

Cualquier consumidor de un archivo debe procesarlo primero a través del sistema de control de versiones. Este es un acoplamiento estrecho, por ejemplo, su IDE favorito se romperá si no es compatible con su VCS.

No, no es una buena práctica rastrear sus correcciones de errores como comentarios en el código. Esto solo genera desorden.

También diré lo mismo para el mensaje de copyright que mencionaste. Si nadie fuera de su empresa verá este código, no hay razón para incluir un mensaje de copyright.

Si está utilizando un software de seguimiento de versiones ( Git , SVN , etc.), debe incluir esas notas en sus mensajes de confirmación. Nadie quiere profundizar en los encabezados de cada archivo de código para generar notas de la versión o ver una descripción general de los cambios realizados. Todos estos registros de cambios deben almacenarse juntos, ya sea en su historial de seguimiento de versiones, su rastreador de defectos o ambos.

Si está buscando una buena lectura sobre este tema, le recomiendo el capítulo cuatro de Clean Code .

Creo que hay otros elementos en esta discusión que a menudo se olvidan, pero son casos en los que algún comentario de revisión es expedito para un equipo.

Cuando se trabaja en un entorno de equipo con una base de código compartida y donde varios miembros del equipo están trabajando potencialmente en las mismas áreas de código, poner un comentario de revisión breve en el alcance correcto (método o clase) indicando que se realizó un cambio puede ser muy útil para resolviendo rápidamente conflictos de fusión o registro.

Del mismo modo, cuando se trabaja en un entorno en el que intervienen varias ramas (características), facilita que una tercera persona (maestro de compilación) identifique qué hacer para resolver posibles conflictos.

Cada vez que tiene que alejarse del IDE y preguntarle a alguien por qué cambió algo, es perjudicial para la productividad de ambos miembros del equipo. Una nota rápida en el alcance correcto puede ayudar a disminuir o eliminar la mayor parte de esta interrupción.

Cualquier información de error directamente asociada a un fragmento de código se vuelve irrelevante cuando la integridad de todo el cambio se modifica mediante una corrección sucesiva.

Solía ​​ser común agregar información en el resumen de funciones cuando teníamos que confiar en herramientas externas (por ejemplo, javadocs) para crear notas de lanzamiento del código. En su mayoría es inútil o redundante con las herramientas modernas de control de versiones.

Solo podría tener sentido como un comentario en un código muy modular, si uno tiene que recurrir a una codificación oscura o no estelar que los futuros desarrolladores estarían tentados a cambiar, sin darse cuenta de la razón detrás de esto, como en una solución alternativa a un error de biblioteca / deficiencia.

Definitivamente no pondría esa información al comienzo del archivo, por lo general, tal cosa pertenece a un sistema de tickets.

Sin embargo, hay algunos casos en los que las referencias al sistema de tickets y / u otra documentación tienen sentido. Por ejemplo, si hay una larga explicación del diseño, o una descripción de alternativas. O información sobre cómo probar cosas, o explicaciones de por qué se hizo exactamente de esa manera. Si eso es corto, pertenece al archivo mismo; Si es largo y / o se trata de una imagen más grande, es probable que desee colocarlo en otro lugar y hacer referencia a él.

El proyecto al que estoy asignado actualmente en el trabajo tenía este tipo de lista de números de error al comienzo de cada archivo; sin embargo, ninguno de los desarrolladores que todavía están en el proyecto lo agregan más. La mayoría de ellos piensan que es una pérdida inútil de espacio, ya que es muy inferior al seguimiento de las confirmaciones de errores en un archivo utilizando nuestro sistema de control de versiones.

En ciertos archivos críticos que han sufrido muchas correcciones y mejoras, estas listas se han vuelto tan grandes que tienes que desplazarte para acceder al código. Cuando greping estas listas pueden dar lugar a varios falsos positivos, ya que un título de error corto o una breve descripción se enumera con cada uno.

En resumen, estas listas son, en el mejor de los casos, inútiles y, en el peor de los casos, una pérdida de espacio masiva y caótica que hace que el código sea más difícil de buscar y localizar.