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

75

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.

version-control coding-standards maintenance

— Wayne Molina
fuente

44

¿Qué sistema de control de versiones estás usando?

— ChrisF

11

Algunas tiendas usaban registros de cambios antes de que existieran sistemas de control de fuente. La inercia y la familiaridad mantienen el registro de cambios.

— Gilbert Le Blanc

2

+1 - Mi equipo también hace esto, y traté de convencer a algunos de ellos de que es el rol del VCS. Los problemas comienzan cuando estos comentarios no se mantienen actualizados con el código real ... Y lo peor es que la administración decidió agregar registros de cambios a cada método también.

— slaphappy

2

+1 - He estado peleando con nuestro desarrollador senior durante casi dos años por esto. Su única razón para agregar estos comentarios inútiles es que hace que la combinación de cambios en los métodos de 3000 líneas sea un poco más fácil. La idea de que un método de 3000 líneas es obsceno se encuentra con desprecio.

— Joshua Smith el

1

Si "tarda demasiado en examinar [sus] registros VCS", está haciendo algo mal.

— Keith Thompson el

46

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.

— George Stocker
fuente

44

Cada vez que lucho con una pieza particular de lógica compleja, los comentarios a veces pueden ayudarme a obtener un contexto sobre por qué la lógica es tan intrincada como lo es. Pero en general estoy de acuerdo contigo.

— maple_shaft

55

Cada desarrollador tiene al menos algunas malas cualidades, sé que no debería, pero no puedo parar :) Cada vez que creo un TODOcomentario, un cachorro muere.

— maple_shaft

32

Eliminar los comentarios de otras personas con prejuicio es una forma de forzar su propio estilo de programación y creencia en los demás. Los programadores junior y pacifistas no responderán, pero de vez en cuando te encuentras con un macho alfa, y luego comienza una pelea que no debería haber sido. Entonces, has leído en un blog inteligente de una persona inteligente que cuando se trata de comentarios, menos es más. Otros podrían no haber leído el mismo libro. Incluso si crees que tienes razón porque algunas personas en SO con 5k + rep están de acuerdo, la dictadura no es la forma de trabajar en colaboración. Trabajé con un macho alfa antes y renuncié.

— Trabajo

8

@Neil Butterworth: re: ructions: el código debe ser maleable. Refactorizarlo, cambiarlo, mejorarlo. Es para eso. No está destinado a ser escrito solo una vez. Nuestra comprensión de los cambios comerciales y cuando eso sucede necesitamos cambiar el código. Tengo muchos problemas con los comentarios, pero lo más relevante para nuestra discusión es que los comentarios rara vez permanecen sincronizados con el código, y en general no explican por qué sucede algo. Cuando eso sucede, es fácil eliminarlo. Si alguien viene a mí y me pregunta por qué eliminé el siguiente comentario file.Open() // Open the file. Me reiría

— George Stocker

55

Hace unos días, escribí un código, un cálculo matemático muy complejo lleno de trigonometría, transformaciones, lo que sea ... Me tomó aproximadamente hora y media escribir menos de 10 líneas de código. Casi nadie a mi alrededor entiende cómo funciona. No lo entenderé en unas pocas semanas también. Por otro lado, por qué es allí es trivial. Entonces, por encima de esas pocas líneas, hay un capítulo completo de texto que explica qué, no por qué. Si viniste y borraste ese comentario, te habría dado un puñetazo en la cara, y me habrían despedido.

— Davor Ždralo

76

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.

— Neil Butterworth
fuente

14

No solo aparecen como otra diferencia, sino que también pueden equivocarse con el tiempo, mientras que cualquier buen VCS siempre podrá decirte quién realmente escribió una línea en particular, así como el historial en torno a esa línea. Lo único peor que los comentarios inútiles son los comentarios dañinos. Estos comentarios comienzan como inútiles y eventualmente se vuelven dañinos, si no totalmente ignorados.

— Ben Hocking

10

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.

— dietbuddha
fuente

8

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.

— John Connelly
fuente

6

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.

— Tangurena
fuente

5

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.

— Tyanna
fuente

5

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!".

— wolfgangsz
fuente

4

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.

— DaveE
fuente

1

+1 Iba a escribir esta respuesta pero me has ahorrado el problema. No solo los procedimientos almacenados se distribuyen como fuente, sino también muchos lenguajes de secuencias de comandos. Uso mucho OpenACS y TCL; a menudo, si un cliente tiene una versión bifurcada de un archivo en particular, la única forma de GARANTIZAR que usted sabe qué versión tiene es leer el registro de cambios. Particularmente útil si está conectado al sitio de un cliente y no puede hacer diferencias fácilmente con el software de control de versiones.

— TrojanName

3

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.

— whatsisname
fuente

1

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.

— Justin Cave
fuente

¿Hay alguna conversión de VCS que no conserve los mensajes de confirmación?

— David Thornley

1

@David: he visto muchas cosas que no. No sé si hubo obstáculos técnicos para hacerlo o si alguien decidió que era más fácil "comenzar de cero" y registrar todo el código en el nuevo VCS el día 1.

— Justin Cave

agregar un comentario explicando por qué un proceso cambió puede ser útil, y algunas veces agregando un comentario explicando cuándo cambió, pero no veo el mérito de poner ese comentario en forma de un registro de cambios. Por un lado, en cierto modo oculta la utilidad del comentario ("Oh, es solo un comentario en el registro de cambios"), y en segundo lugar, alienta los comentarios innecesarios adicionales en el registro de cambios (reforzando el n. ° 1).

— Ben Hocking

Dejar de usar la fuente visual segura? Todos los sistemas de control de fuente modernos y útiles manejan los registros de cambios correctamente. Sabemos esto por definición porque si no lo hicieran, no se considerarían útiles. Dedique 30 minutos a aprender a usar el control de fuente que tiene, lo hará mucho más efectivo que simplemente rezar a alguien que conozca sus herramientas y le ahorrará algunas migajas. Sin mencionar que, a menudo, el historial de código es irrelevante, solo está probando y escribiendo ahora, ahora.

— ebyrob

En cuanto a "cambiar el control de origen": casi todos los sistemas modernos pueden mover el historial uno a otro, generar archivos de cambio de nivel de proyecto individuales o, con un pequeño esfuerzo, incrustar sus registros de cambios en el archivo de origen (cuando sea apropiado en un movimiento no antes). Entonces, la tecnología está ahí, el problema es la gente que elige no usar el control de fuente correctamente.

— ebyrob

1

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.

— Sverre Rabbelier
fuente

1

¿Qué licencias dicen eso?

— Trasplazio Garzuglio

2

Trabajé en un lugar donde el cumplimiento de Sarbanes Oxley en el que creían exigía bloques de cambio en los archivos fuente. También utilizaron PVCS (también conocido como "Dimensiones") a lo largo de los años, por lo que realmente no tenían control de versión, pero ¿qué sabía yo?

— Bruce Ediger

@Marco: No lo recuerdo o me hubiera vinculado a él.

— Sverre Rabbelier

1

La Sección 2a de la GPLv2 lo requiere. La mayoría de los proyectos lo ignoran, algunos tienen un solo archivo "ChangeLog" (a menudo generado desde su VCS).

— dsas

0

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

— briddums
fuente

1

Personalmente, me resulta un poco complicado cuando un archivo de 200 líneas se convierte en 1,000 líneas de largo debido a la adición de un registro de cambios en cada archivo fuente. Este ruido extra en realidad oculta lo que es importante en poco tiempo.

— ebyrob