¿Hay algún punto para incluir un "registro de cambios" en cada archivo de código cuando está utilizando el control de versiones?

Tenía la impresión de que un sistema de control de versiones eliminaba la necesidad de tener "registros de cambios" en todas partes del código. A menudo he visto el uso continuo de registros de cambios, incluidos grandes bloques largos al comienzo de los procedimientos almacenados con una gran sección bloqueada para cambios en el archivo y ensuciando el código con cosas como:

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

y:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

La razón de esto, como me explicaron, es que lleva demasiado tiempo examinar nuestros registros de VCS tratando de encontrar quién cambió qué y por qué, mientras lo tiene en el archivo de código, ya sea en la parte superior o cerca de la correspondiente cambiar, hace que sea fácil ver quién cambió qué y cuándo. Si bien veo el punto de eso, parece redundante y solo una especie de "Eh, realmente no entendemos cómo usar nuestro VCS correctamente, por lo que no nos molestaremos en absoluto con esas cosas".

¿Qué piensas? ¿Utiliza tanto los comentarios como el registro? Sólo el registro? ¿Le resulta más fácil codificar cuando puede ver arriba de un bloque de código que John Smith cambió el método para verificar XYZ hace una semana, en lugar de tener que buscar en los registros y comparar archivos de código en una herramienta Diff?

EDITAR: Usando SVN, pero básicamente solo como un repositorio. Sin sucursales, sin fusiones, nada excepto log + almacenamiento.

Tiendo a eliminar comentarios en el código. Y por borrar, quiero decir, con prejuicio . A menos que un comentario explique por qué una función particular hace algo, desaparece. Adiós. No pases ir.

Por lo tanto, no debería sorprenderle que también elimine esos registros de cambios, por la misma razón.

El problema con el código comentado y los comentarios que se leen como libros es que realmente no sabes lo relevante que es y te da una falsa sensación de comprensión de lo que realmente hace el código.

Parece que su equipo no tiene buenas herramientas para su sistema de control de versiones. Como dijo que está usando Subversion, me gustaría señalar que hay muchas herramientas que lo ayudarán a administrar su repositorio de Subversion. Desde la capacidad de navegar por su fuente a través de la web, hasta vincular sus conjuntos de cambios a errores específicos, puede hacer mucho para mitigar la necesidad de estos 'registros de cambios'.

Muchas personas han comentado y dicen que tal vez estoy en un error al eliminar comentarios. La gran mayoría del código que he visto que se ha comentado ha sido un código incorrecto, y los comentarios solo han oscurecido el problema. De hecho, si alguna vez comento un código, puede estar seguro de que estoy pidiendo perdón al programador de mantenimiento porque estoy relativamente seguro de que querrán matarme.

Pero para que no pienses que digo que los comentarios deberían eliminarse en broma, este envío diario de WTF (desde una base de código en la que trabajé) ilustra mi punto perfectamente:

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

Oh ... Las historias que podría contarte sobre esa base de código, y lo haría, excepto que todavía está en uso por una de las organizaciones gubernamentales más grandes.

Esos "registros de cambios" incrustados en el código son particularmente molestos. Simplemente aparecen como otra diferencia cuando difieren las revisiones, y una que realmente no le importa. Confíe en su VCS: la mayoría tiene una función de "culpa" que le mostrará muy rápidamente quién cambió qué.

Por supuesto, lo realmente horrible fue esa característica de los VCS "antiguos" en los que podía tener el registro VCS real incrustado en los archivos fuente. Hecho fusión casi imposible.

Tengo un solo archivo ChangeLog para cada proyecto que se completa automáticamente con ciertos mensajes de confirmación.

No tenemos comentarios incrustados en ChangeLog. Si lo hiciéramos, los eliminaría y tendría una "conversación" con la persona que los agrega. Creo que son indicativos de no entender las herramientas que usa, específicamente las vcs.

Tenemos un formato para enviar mensajes que hace que sea más fácil manipular los registros. También rechazamos mensajes de confirmación inútiles o ambiguos.

Yo personalmente aborrezco los registros de cambios dentro del archivo fuente del código. Para mí, se siente como si violara un principio de ingeniería de software en el sentido de que cualquier cambio que realice debe hacerse en varios lugares. Muchas veces la información del registro de cambios es completamente inútil y sin importancia. En mi humilde opinión, los cambios en el software deben documentarse cuando se registra el código.

Pero que se yo...

Creo que si existe la insistencia en implementar la práctica de mantener un registro de cambios dentro del código fuente, el registro de cambios debe limitarse a los cambios que afectan la API / interfaz pulic de la clase. Si está haciendo cambios dentro de la clase que no van a romper ningún código que lo use, registrar estos cambios en un registro de cambios es, en mi opinión, un desorden. Sin embargo, puedo ver cómo a veces puede ser útil poder verificar la parte superior del archivo de código fuente para obtener documentación sobre cualquier cambio que pueda haber roto algo para cualquier otra persona. Solo un resumen de cómo el cambio podría afectar la API y por qué se realizó el cambio.

Por otro lado, mi tienda principalmente hace cosas de C #, y siempre usamos comentarios XML en línea para documentar nuestra API, por lo que leer la documentación sobre los cambios públicos de la API es más o menos tan simple como utilizar intellisense.

Creo que insistir en un registro de cambios dentro del archivo fuente solo agrega fricción innecesaria a la máquina y derrota uno de los propósitos de implementar un sistema de control de versiones en primer lugar.

La última compañía en la que trabajé tenía software que tenía 17 años de historia, desarrollo y actualizaciones anuales. No todas las migraciones de un sistema de control de versiones al siguiente conservarían comentarios o notas de registro. Tampoco todos los desarrolladores durante esos años mantuvieron ninguna coherencia con los comentarios / notas de verificación.

Con comentarios en el código fuente, el historial arqueológico de los cambios se mantuvo como notas, no como código comentado. Y sí, todavía están enviando el código VB6.

El control de versiones puede reemplazar esos comentarios de registro de cambios en el código si los desarrolladores de su equipo lo están utilizando correctamente.

Si su equipo no agrega comentarios en el check-in, o deja comentarios poco útiles, entonces será bastante difícil encontrar la información que está buscando en el futuro.

En mi empresa actual, estamos obligados a enviar un comentario con cada registro. No solo eso, sino que se espera que adjuntemos cada registro con un boleto en Jira. Cuando mira en Jira en el futuro, puede ver todos los archivos que se registraron y cuándo para ese problema junto con el comentario que quedó. Es bastante útil.

Básicamente, el control de versiones es solo una herramienta, es la forma en que su equipo usa esa herramienta lo que le proporcionará las ventajas que está buscando. Todos los miembros del equipo deben estar de acuerdo con la forma en que lo utilizarán para proporcionar un mejor seguimiento de corrección de errores y revisiones de código limpias.

Esto es un remanente de los días en que los registros de VCS eran confusos y los sistemas de VCS eran difíciles de manejar (recuerdo esos días, en algún lugar del final de los años 80).

Su sospecha es completamente correcta, estos comentarios son más un obstáculo que una ayuda y cualquier VCS moderno le permitirá encontrar exactamente lo que está buscando. Por supuesto, usted (y sus colegas) tendrán que gastar aprox. 30-60 minutos aprendiendo a manejar todas estas características (lo cual, sospecho, es en realidad la razón por la cual estos comentarios siguen ahí).

Lo mantengo (casi) con George. Los comentarios en el código solo están realmente justificados si explican algo que no es inmediatamente visible en el código mismo. Y eso ocurre raramente en un buen código. Si tiene la necesidad de tener muchos comentarios en su código, es un olor propio y grita "¡refactoríceme!".

Todavía los incluimos en la fuente del procedimiento almacenado porque así es como podemos saber exactamente qué versión está en su lugar en un cliente. El resto de la aplicación se distribuye compilada, por lo que tenemos números de versión de módulo que se vinculan de nuevo a la fuente, pero los SP se distribuyen como fuente a los clientes para la compilación local en la base de datos.

Nuestro código heredado de PowerBuilder todavía los usa, pero creo que eso es solo un factor de comodidad para ciertas personas. Eso también se compila para su distribución, por lo que (en mi opinión, deberían) usar el maldito historial de VCS.

Si está utilizando SVN, hacerlo es una pérdida de tiempo y totalmente inútil.

SVN tiene la función de culpar. Eso le dirá exactamente quién hizo cada línea en un archivo determinado y cuándo.

Los comentarios del registro de cambios son excepcionalmente útiles en el código cuando ayudan a un desarrollador posterior a hacer mejores preguntas sobre los nuevos requisitos. Cuando un desarrollador ve un comentario, por ejemplo, que Fred hizo el campo Foo requerido hace 6 meses para satisfacer algún requisito, ese desarrollador sabe que debe hacer alguna pregunta antes de implementar la última solicitud para hacer que Foo sea opcional. Cuando se trata de sistemas complejos, es probable que diferentes partes interesadas tengan diferentes prioridades y diferentes deseos. Los comentarios del registro de cambios pueden ser muy útiles para documentar cuáles de estas compensaciones se han realizado para evitar problemas en el futuro.

Ahora, si cada desarrollador verificara el historial completo de cada línea de código antes de realizar cualquier cambio, tener estos comentarios en el código sería redundante. Pero esto es muy poco realista tanto desde el punto de vista del flujo de trabajo: la mayoría de los desarrolladores simplemente cambiarían la validación sin investigar el historial de quién lo agregó y por qué, y desde el punto de vista tecnológico, un sistema de control de versiones tendría dificultades para rastrear el "mismo "línea de código si se ha movido de una línea a otra o se ha refactorizado a una clase diferente. Es mucho más probable que se vean los comentarios en el código y, lo que es más importante, que se solicite a un desarrollador posterior que note que un cambio aparentemente simple puede no ser tan simple.

Dicho esto, los comentarios del registro de cambios en el código deberían ser relativamente raros. No estoy recomendando que se agreguen comentarios de registro de cambios cada vez que se refactoriza un poco de código o cuando se corrige un error real. Pero si el requisito original era "Foo es opcional" y alguien aparece y cambia el requisito a "Se requiere Foo para admitir la barra de proceso posterior", es algo por lo que consideraría agregar un comentario. Debido a que existe una gran posibilidad de que algún futuro usuario / analista desconozca el proceso posterior de Bar y desconozca la razón por la cual Foo fue requerido y solicitará que Foo sea opcional nuevamente y cause dolores de cabeza en el proceso de Bar.

Y esto es antes de considerar que las organizaciones pueden decidir cambiar su sistema de control de versiones con cierta frecuencia, especialmente a medida que crecen desde pequeñas empresas con un puñado de desarrolladores hasta compañías mucho más grandes. Estas migraciones a menudo darán como resultado la pérdida de los comentarios del registro de cambios; solo se conservarán los comentarios en el código.

Me sorprende ver que nadie mencionó esto, pero ¿no es la razón original para que esto cumpla con los requisitos de licencia? Es decir, algunas licencias dicen que cualquier cambio que realice en el archivo debe anotarse en el archivo mismo.

La razón por la que continuamos manteniendo un registro de cambios en nuestra sección de comentarios es para facilitar su uso. A menudo, al depurar un problema, es más fácil desplazarse hasta la parte superior del archivo y leer el registro de cambios que abrir el archivo de control de origen, ubicar el archivo dentro de él y encontrar los cambios realizados