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

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

Por lo tanto, no debería sorprenderte que yo también eliminaría 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 qué tan relevante es y te da una falsa comprensión de lo que realmente hace el código.

Parece que su equipo no tiene buenas herramientas en torno a su sistema de control de versiones. Como dijo que está usando Subversion, me gustaría señalar que hay muchas herramientas que le ayudarán a administrar su repositorio de subversion. Desde la capacidad de navegar 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'.

He tenido muchas personas que comentan y dicen que quizás me equivoque al eliminar comentarios. La gran mayoría del código que he visto que ha sido comentado ha sido un código malo, y los comentarios solo han ocultado el problema. De hecho, si alguna vez comento un código, puede estar seguro de que le pediré perdón al programador de mantenimiento porque estoy relativamente seguro de que querrán matarme.

Pero para que no piense que debo decir que los comentarios se deben eliminar en la broma, este envío diario de WTF (de un código I) trabajado en) ilustra perfectamente mi punto:

/// 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 del mundo.

Los "registros de cambios" incrustados en el código son particularmente naff. Simplemente se muestran 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 la característica de los VCS "antiguos" en los que podría tener el registro VCS real incrustado en los archivos de origen. Hecho fusión casi imposible.

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

No tenemos comentarios de ChangeLog incrustados. Si lo hiciéramos, los eliminaría y hablaría con la persona que los agregó. Creo que son indicativos de no entender las herramientas que usa, específicamente las vcs.

Tenemos un formato para enviar mensajes que facilita la grep de los registros. También rechazamos los mensajes de confirmación inútiles o ambiguos.

Personalmente aborrezco los registros de cambios dentro del archivo de código fuente. Para mí es como si violara un principio de ingeniería de software en el sentido de que cualquier cambio que realice debe realizarse 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 se deben documentar cuando verifique el código.

Pero qué sé ...

Creo que si hay una 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 de la clase. Si está realizando 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 solo un desorden en mi opinión. Sin embargo, puedo ver cómo a veces puede ser útil poder revisar la parte superior del archivo de código fuente para obtener documentación sobre cualquier cambio que pueda haber roto algo para otra persona. Solo un resumen de cómo el cambio podría afectar la API y por qué se realizó el cambio.

Por otra parte, 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 cambios públicos en la API es más o menos tan simple como utilizar intellisense.

Creo que insistir en un registro de cambios dentro del archivo de origen es solo agregar fricciones innecesarias a la máquina y anular uno de los propósitos de implementar un sistema de control de versiones en primer lugar.

La última empresa en la que trabajé tenía un software con 17 años de historia, desarrollo y actualizaciones anuales. No todas las migraciones de un sistema de control de versión al siguiente conservarán los comentarios o las notas de verificación. Tampoco todos los desarrolladores a lo largo de esos años mantuvieron ninguna coherencia con los comentarios / notas de check-in.

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 código VB6.

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

Si su equipo no está agregando comentarios en el check-in, o está dejando comentarios inútiles, 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 cheque con un boleto en Jira. Cuando mire en Jira en el futuro, podrá ver todos los archivos que se han registrado y cuándo, para ese problema, junto con el comentario que se dejó. Es bastante práctico.

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

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 en el backend de los 80).

Su sospecha es totalmente 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 que estos comentarios siguen ahí).

Lo guardo (casi) con George. Los comentarios en el código solo están realmente justificados si explican algo que no es inmediatamente visible en el propio código. Y eso ocurre raramente en buen código. Si tienes la necesidad de tener un montón de comentarios en tu código, ese es su propio olor y grita "¡Refactorízame!".

Todavía los incluimos en la fuente de procedimientos almacenados porque es así como podemos decir exactamente qué versión está implementada en un cliente. El resto de la aplicación se distribuye de forma 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 aún 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 (IMO deberían) usar el historial VCS friggin.

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

SVN tiene la función de culpa. Eso le dirá exactamente quién hizo cada línea en un archivo dado, 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 con respecto a los nuevos requisitos. Cuando un desarrollador ve un comentario, por ejemplo, que Fred hizo el campo de Foo requerido hace 6 meses para satisfacer algún requisito, ese desarrollador sabe que debe hacer una pregunta antes de implementar la última solicitud para hacer que Foo sea opcional. Cuando se trata de sistemas complejos, es probable que las diferentes partes interesadas tengan diferentes prioridades y diferentes deseos. Los comentarios sobre el registro de cambios pueden ser muy útiles para documentar cuáles de estas compensaciones se han hecho 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 en una clase diferente. Es mucho más probable que se vean los comentarios en el código y, lo que es más importante, incitar a un desarrollador posterior a observar 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 abogando por que se agreguen comentarios de registro de cambios cada vez que se refactorice un poco de código o cuando se corrija 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 en sentido descendente", es algo para lo que consideraría encarecidamente agregar un comentario. Debido a que existe una gran posibilidad de que algún futuro usuario / analista no esté al tanto del proceso de Barra posterior y no sepa por qué se requirió a Foo y pedirá que Foo vuelva a ser opcional y cause dolores de cabeza en el proceso de Barra.

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 de pequeñas empresas con un puñado de desarrolladores a compañías mucho más grandes. Estas migraciones a menudo provocarán la pérdida de los comentarios del registro de cambios: solo se conservarán los comentarios en el código.

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

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, cuando se depura 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