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

He visto esto hecho antes, tanto de forma manual por los autores como de forma automática por los scripts y los activadores integrados con los sistemas de control de versiones para agregar el autor, el comentario de registro y la información de la 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 un número de ID de tarea en un comentario de registro a un elemento en la herramienta de seguimiento. Si tiene todos sus defectos, solicitudes de mejoras y tareas de trabajo en la herramienta, puede proporcionar enlaces de esa manera. Por supuesto, esto viene con la desventaja de una dependencia en esas herramientas para el proyecto.

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

Y si el código ha cambiado de manera que no haya tentación de llamar directamente a foo() , 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 solo al usar registros de confirmación es la posibilidad de crear inconsistencia. Los archivos de origen se llenan de cantidades ilimitadas de cosas que nunca miras.

El único aspecto positivo que puedo discernir es que puedes reconstruir el historial de origen sin acceso al control de versiones, por ejemplo. al estudiar una impresión. Pero muy pocas personas son lo suficientemente competentes para seguir las complejidades del desarrollo de software, mientras que al mismo tiempo no pueden entender el control de versiones.

No.

Eso es lo que hizo la gente 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, IMHO, una muy mala idea. Después de la revisión número 100, tendrá un 90% de comentarios y un 10% de código. No lo consideraría tan limpio y legible.

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

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

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

Sí, desordena el código, pero ayuda a encontrar la razón de por qué ese fragmento de 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 crees que son importantes, pero solo serían ruidos en los comentarios.

Creo que tienes dos problemas aquí. Primero, ¿por qué debería confiar únicamente en la diferencia 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í mismo.

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

Una vez que pongas 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 características, junto con la razón por la que está cambiando este archivo, le puede dar una idea de la profundidad que necesita para profundizar en la historia y, posiblemente, examinar las diferencias. Recibí una solicitud para "Cambiar de nuevo a la fórmula original". Sabí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. Saca este lío del código de producción. Poder deslizar fácilmente las 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 estás en un entorno sin tales "lujos", un archivo de texto se encuentra cerca de tus fuentes. Pero te recomiendo encarecidamente que estés en un entorno así para comenzar a construir un caso para invertir en un sistema de seguimiento de errores y VCS :)

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.

Aunque 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 de gran ayuda, especialmente si mantengo el código.

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

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

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

Se requiere que cualquier consumidor de un archivo lo procese a través del sistema de control de versiones primero. Esto es un acoplamiento apretado, por ej. su IDE favorito se romperá si no es compatible con su VCS.

No, no es una buena práctica hacer un seguimiento de 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 va a 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, en su rastreador de defectos o en ambos.

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

Creo que hay otros elementos de esta discusión que a menudo se olvidan, pero son casos en los que algunos comentarios de revisión son rápidos para un equipo.

Cuando trabaje 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, coloque un breve comentario de revisión en el alcance correcto (método o clase) que indique que se realizó un cambio. Muy útil para resolver rápidamente los conflictos de combinación o registro.

Del mismo modo, cuando se trabaja en un entorno donde hay varias ramas (características) involucradas, es más fácil para una tercera persona (maestro de la construcción) identificar qué hacer para resolver conflictos potenciales.

Cada vez que tenga que alejarse del IDE y preguntar a alguien por qué cambiaron 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 por una corrección sucesiva.

Solía ser común agregar información en el resumen de la función cuando teníamos que confiar en herramientas externas (por ejemplo, javadocs) para crear notas de la versión 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 una pieza de 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 saber la razón detrás de esto, como en una solución 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 explicación larga 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 propio archivo; si es larga y / o se trata de una imagen más grande, probablemente querrá ponerla en otro lugar y hacer referencia a ella.

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 aún están en el proyecto se le agrega. La mayoría de ellos piensan que es una pérdida inútil de espacio, ya que es muy inferior al seguimiento de errores cometidos en un archivo que utiliza nuestro sistema de control de versiones.

En ciertos archivos críticos que se han sometido a muchas correcciones y mejoras, estas listas se han vuelto tan grandes que tiene que desplazarse más allá de ellas para obtener el código. Cuando estas listas pueden resultar en varios falsos positivos, como un título de error corto o una descripción breve se muestra con cada uno.

En resumen, estas listas son, en el mejor de los casos, inútiles y, en el peor, un desperdicio de espacio masivo y caótico que hace que sea más difícil buscar y localizar el código.