Aquí podría ser tu PUBLICIDAD


Historial de modificaciones en un archivo

votos
2

He trabajado en algunos lugares que no han usado el control de fuente. Parecían adquirir el hábito de poner comentarios sobre el código que cambiaban explicando el cambio para que las cosas pudieran revertirse.

He descubierto que esto hace que el código sea muy difícil de leer, y me he mostrado inflexible en que tales comentarios no son necesarios después de introducir el control de fuente, ya que el historial de revisión le permitirá hacer coincidir los tickets con los cambios.

Sin embargo, ahora, no estoy tan seguro, creo que puede ser bueno documentar las principales revisiones de un archivo en un archivo, así como en los mensajes de confirmación. Esto debería hacer que el código sea más legible. ¿Las personas tienen una forma de mejores prácticas de documentar los cambios en el código, para que no sea demasiado abarrotado, pero sigue siendo explicativo para alguien que intenta leerlo?

Para ser claros, no estoy hablando de una lista de cambios en el encabezado del archivo (que es un argumento completamente diferente) sino de comentarios en el código.

Publicado el 12/03/2009 a las 15:38
fuente por usuario Jeremy French
En otros idiomas...        العربية       

8 respuestas

votos
5

La mayoría de los sistemas de control de origen tienen un comando "anotar" o "culpar". Muestra qué código cambió con cada revisión.

Dado que esta información no cambia el comportamiento del programa ni facilita su comprensión, no pertenece al programa.

Respondida el 12/03/2009 a las 03:45
fuente por usuario John Saunders


Aquí podría ser tu PUBLICIDAD


votos
3

Si el comentario es sensible al tiempo, no lo hagas, es una mala idea. Ponga un comentario en el archivo fuente en el sistema de control de versiones.

Veo este problema todo el tiempo en el trabajo. La base de código en la que estoy trabajando actualmente se remonta a 1979. Puede imaginar la dificultad con comentarios como el siguiente que se han acumulado durante ese tiempo:

"La línea siguiente parece corregir el error xyz, revertirá si se producen problemas imprevistos"

Me doy cuenta de que no es un comentario muy descriptivo en primer lugar, pero ese tipo de cosas en svn / cvs / etc. es realmente muy útil. Un comentario como ese en el código siembra las semillas de la duda. ¿Se puede eliminar el comentario? ¿Es el problema imprevisto que me ha obligado a tener que mirar hacia atrás en el código relacionado con este comentario? etc.

Respondida el 12/03/2009 a las 03:51
fuente por usuario sipwiz

votos
3

La documentación presente en el código debe describir el código que está cerca. Si el código cambia, la documentación también debería cambiar en consecuencia. El sistema de control de versiones debe encargarse de gestionar qué cambió y por qué cambió. Deje que el código y su documentación hagan su trabajo (Hacer y describir cómo / por qué se hacen esas cosas) y dejar que el sistema de control de versiones haga su trabajo (controlar / documentar versiones y cambios).

Siempre que comiences a indicar el historial en el presente (código actual), estás pidiendo problemas. Solo piense en cómo sería una área de código particularmente cambiante si tuviera una serie de cambios?

Respondida el 12/03/2009 a las 03:46
fuente por usuario cdeszaq

votos
2

Me pregunto cómo saber lo que el programa usó para hacer ayuda a comprenderlo ahora. Usted dice que ayuda a la legibilidad. ¿Cómo?

Ahora, cuando algo se cambia porque la forma anterior no funcionó y la nueva forma es contraria a la intuición, creo que debería comentarse en código, porque es necesario saber para siempre "Esto no funcionó, no lo hagas hazlo de nuevo. Sé que parece que tendría más sentido. Aún así no lo hagas ". De lo contrario, no veo que eso ayude.

Respondida el 13/03/2009 a las 04:19
fuente por usuario Instance Hunter

votos
1

No piense que comentar cambios dentro de un código siempre es posible de forma explicativa.

Pero me gustaría decir sobre "Comienzo del historial de modificaciones en el archivo". Dudo que esto sea útil en absoluto. A menos que quisiera saber qué versiones de un archivo comparar para ver la diferencia que se introdujo con alguna tarea "NNNN". En el archivo begin hay una línea "NNNN date - small description". Y nuestro control de fuente puede "decir" quién y en qué versión se introdujo esta línea.
Entonces, sin esta línea, revisaría todas las versiones para encontrar la correcta.

Respondida el 12/03/2009 a las 03:46
fuente por usuario Mykola Golubyev

votos
0

Voy a tener una puñalada para responder esto yo mismo.

Documentar cada cambio en la fuente hace que sea difícil de leer, sin embargo, si hay una pieza de código particularmente contradictoria allí y se introdujo para un boleto en particular, ponga una nota de por qué el código es extraño.

Pero el código aún debe estar documentado. Entonces, mientras haces no pongas

/* ticket 101: add blink tag to headers, JF - 20010102 */

Es posible que desee poner en

/* make headers blink */

Muy a menudo, cuando las personas dejan de hacer el primer tipo de comentarios, reducen enormemente sus comentarios y esto es malo.

Respondida el 16/03/2009 a las 05:49
fuente por usuario Jeremy French

votos
0

Cada método en nuestra base de código tiene su propio historial de cambios. Cuando se cambia el código de un método, su encabezado recibe una nueva entrada. El código en sí no se llena de comentarios de historial, solo el encabezado del método. Cada entrada del historial de cambios consta de una o dos líneas que describen brevemente el motivo del cambio de código en términos generales. La entrada también contiene un número que hace referencia a un documento de cambio. El documento de cambio también contiene enlaces a informes de errores, proyectos de desarrollo, documentos de diseño, etc.

Tales entradas son invaluables, ya que a menudo le dan una idea de por qué el código es como es. Si está allí para corregir un error, el seguimiento del historial indicará invariablemente qué cambio de código introdujo el error, qué estaba intentando hacer el cambio y, por lo tanto, qué más debe tener en cuenta al decidir una solución.

OTOH: resmas de comentarios en el cuerpo del código que describen lo que hace y quién lo cambió cuando son solo ruido.

Respondida el 12/03/2009 a las 04:47
fuente por usuario lilburne

votos
0

Creo que es bueno documentar cambios importantes o refactorizaciones como comentarios en el código. Estoy de acuerdo en que es un poco complicado leer un montón de comentarios, pero creo que es bastante fácil ignorar los comentarios y tratar de leer el código. Si algo es confuso, o tiene la tentación de cambiar algo, y hay un comentario cerca, estará mucho más inclinado a leer el comentario, en lugar de hacer diffs con versiones anteriores para ver qué ha cambiado y por qué.

Respondida el 12/03/2009 a las 03:45
fuente por usuario Andy White