version-control - tool - like jira open source
Comentarios de errores (18)
¡Es algo bueno!
La persona que está mirando el código es poco probable que aprecie el historial completo del código y es probable que deshaga un cambio muy importante porque es posible que no haya funcionado anteriormente en esta área del código. Puede explicar un código que de otra manera parece insano o un requisito del cliente que es equivalente a lo extraño.
No siempre se pueden capturar los detalles minuciosos de los requisitos del cliente a través de la arquitectura y el código, especialmente cuando piden algo estúpido. Por lo tanto, comienzas con lo sensato y luego refinas o pirateas el código en el estúpido cuando te obligan a hacerlo, los números de error respaldan la intención del código loco.
Por qué agregarías
// Error 1024
comentarios en una base de código controlado de origen? La mayoría de los sistemas de seguimiento de fallas y control de fuentes están mejor equipados para realizar un seguimiento de esta información. En el control de fuente, una etiqueta o comentario se puede usar con el checkin. En un rastreador de errores, el número de revisión se puede agregar a la resolución del error. Entonces, ¿por qué comentar el código? Especialmente porque la relevancia de estos comentarios es de muy corta duración y tienden a acumular basura en la base de códigos.
Creo que este es un caso de "Tengo un martillo, eso debe ser un clavo". Su editor de texto o IDE no es su única herramienta para administrar el código.
La historia se mantiene mejor externamente al código. El significado del código se debe describir en los comentarios cuando no sea inmediatamente obvio.
Estoy de acuerdo en que los números de error deberían estar en los mensajes de confirmación de control de fuente.
En definitiva, creo que es una mala práctica. Es mejor incluir por qué existe el error (los foos de tipo Y no tienen la propiedad Z). Puede incluir un "más en BugId 12345" junto con eso si lo desea.
Si se está integrando en múltiples niveles, una vista de código fuente en trac puede vincular directamente al BugId.
Encontré uno de estos útiles el otro día en nuestra base de códigos.
Dije "¿por qué está llamando a la función de inicialización por segunda vez, tan tarde en el flujo de trabajo?"
El comentario sobre el error me dejó corregir la descripción del problema. Cuando reorganicé el código, estaba seguro de incluir ese error en mis pruebas y no reintroducirlo.
Aunque diré que, en general, estoy de acuerdo con usted y no los inserto yo mismo.
Hubiera preferido que el desarrollador en cuestión solucionó el error de una manera más significativa, por lo que no tenía que preguntarse sobre el código en primer lugar.
Este tipo de comentarios ES muy útil: ¿qué sucede cuando se cambian las herramientas de seguimiento de errores o de control de origen? Una referencia a BZ1722 frente a FB3101 le indicaría qué herramienta de seguimiento verificar (Bugzilla o FogBugz, por ejemplo).
Estoy de acuerdo con usted en que el comentario como este no es realmente útil y es demasiado breve.
Sin embargo, es extremadamente útil e importante comentar el código con referencias a los registros en el sistema de seguimiento de defectos (o, en ese caso, a cualquier repositorio de KM que pueda tener).
En ocasiones, se cambia un código para implementar una solución a un cierto problema con el comportamiento de la aplicación. A veces la solución introducida no es de ninguna manera lógica. A menudo ocurre que cuando un código es actualizado por otra persona, esta "mala" pieza de código se elimina como parte del esfuerzo de refaccionamiento.
Por lo tanto, marcar un código como perteneciente a una corrección de errores particular lo hace visible durante el refaccionamiento, lo que hace que el desarrollador revise la descripción del error antes de cambiar el código. También ayuda en la situación en la que el error se vuelve a abrir: si tiene que cambiar la misma parte del código varias veces, puede considerar invertir tiempo en una solución alternativa.
PD, podría considerar útil este artículo sobre MS Office de Joel On Software. Hasta donde yo sé, el código de MS Office y MS Windows está lleno de comentarios similares que explican las decisiones tomadas por los desarrolladores que se fueron hace mucho tiempo.
Imagine que tiene un nuevo error que rastrea al cambio en la revisión 12345. Observa los registros e inmediatamente le dice que el error 1024 fue la razón por la cual se realizó el cambio.
A continuación, puede ir a ver 1024 para ver qué, por qué y cuándo antes de hacer una nueva solución, la ''que los gobierna a todos''.
Si el número de error no está en el mensaje de compromiso, entonces debe buscar el error que confirmó una confirmación, y que podría ser varios (si el error se informa más de una vez).
Le pegas al clavo en la cabeza con "la relevancia es de muy corta vida y tienden a acumular basura en la base del código".
Cada fragmento de crumble inútil que se acumula en los archivos fuente los hace un poco menos legibles y difíciles de mantener. Elimine todo lo que no agrega valor. "Bug 12345" tiene poco valor ahora, y no tendrá ninguno en unas pocas semanas.
Lo encuentro útil cuando explico un código que de otra manera parecería incorrecto, y también para usarlo en los mensajes de confirmación.
Lo hice hasta Visual Studio 2008 enviado con anotación. Fue útil al mirar hacia atrás en el código anterior para ver de inmediato que al menos se pensaba detrás de una decisión de código en particular.
Sí, sé que se puede comparar con versiones anteriores, pero eso es un dolor de cabeza cuando solo se necesita un rápido sentirse bien acerca de las actualizaciones de códigos menores.
Me sorprende cuánta gente se opone a esto. Mi sentimiento personal sobre esto es que estas son una muy buena idea. Estoy de acuerdo con un comentario anterior que debería incluir más que solo el número de error, y preferiblemente incluir un breve resumen y un enlace al sistema de seguimiento de errores, si corresponde.
El beneficio de estos comentarios es obvio en un proyecto anterior con historial y una gran cantidad de correcciones de errores anteriores. No tiene que hacer estos comentarios en todas partes, pero son muy útiles cuando se colocan antes de un bloque de código que podría no tener sentido sin contexto. En cualquier tipo de sistema razonablemente complejo, habrá trozos de código que parecen ilógicos o innecesarios sin contexto.
Debido a las interacciones con el sistema o las soluciones temporales anteriores, el código es necesario. Para evitar que alguien vuelva a introducir un error reparado, es de gran ayuda denotar el error que el bloque de código está diseñado para corregir, preferiblemente con algún tipo de explicación adjunta. De lo contrario, depende de que alguien revise el historial de confirmaciones con cuidado por un motivo registrado en el registro de confirmación, lo cual es muy poco probable, especialmente si alguien está refabricando el código.
EDITAR : Me refiero específicamente a poner estos con un bloque de código que es inusual o necesita el contexto adicional. No es útil ni necesario comentar cada corrección de error tipográfico que hagas :-)
No me gusta este tipo de graffiti. Al igual que otras formas de vida desagradables, se acumulan con el tiempo, estrangulando la base de códigos.
El problema realmente comienza cuando las personas hacen correcciones de errores que se superponen con una corrección de error previa. Luego tiene números de error que etiquetan una sección de código que simplemente es incorrecta o engañosa.
Nunca deberías agregar solo el número de error. Debe agregar el número de error y el asunto, y cualquier calificador si realizó múltiples controles para un único error:
Error 1111 - Foo detenido en sistemas de 64 bits. Solución # 2 porque se volvió a abrir después de la fusión a la línea externa.
Algunos sistemas tienen integración de número de errores. En mxr.mozilla.org, el número de error en la pantalla de registro de cvs se convierte automáticamente en un enlace al número bugzilla.mozilla.org. Cuando estás cavando en el código, este es un gran ahorro de tiempo. Creo que Fogbugz tiene una característica similar ...
Además, incluso si su sistema no lo hace, a menudo ayuda porque nadie quiere ver todo el contexto del cambio en los comentarios, para eso es el rastreador de errores.
Pura pereza Claro, toma más tiempo en el largo plazo, pero en el corto plazo "// Bug 1024" no requiere ningún esfuerzo en absoluto. Cuantos más códigos tenga, peor es esto.
Si está navegando por un código fuente desconocido y ve algo que no es obvio, es bueno saber el motivo. Sin embargo, es una decisión acertada, no todas las correcciones de errores necesitan una explicación de este tipo: probablemente la mayoría pueda escaparse sin ella.
Si hay motivos suficientes para creer que alguien querría saber el número de error al observar parte del código, agregar un comentario que mencione el error puede ser bastante bueno (sin embargo, también parafraseará los bits importantes del error).
Sí, los mensajes de confirmación del control de origen también deben contener los números de error, y mirar los registros de revisión puede darle la misma información ... pero si la misma parte del código se cambia varias veces, pero los detalles aprendidos del error inicial aún aplica, podría tomar un tiempo encontrar el cambio original para aprender sobre ese error.
Además, surgen situaciones cuando hay una buena razón para mover el código de una clase a otra, o para cambiar el nombre de los archivos, lo que haría aún más difícil encontrar la raíz de la razón detrás de una determinada sección de código (cambiar el nombre no tanto de un problema con SVN, pero un problema con CVS).
Trabajamos en un sistema a gran escala con muchos desarrolladores y múltiples ramas lanzadas.
Estos comentarios de referencia de errores realmente pueden ser muy útiles durante la transferencia de una rama a otra, especialmente dado que el sistema SCM que utilizamos es muy pobre en funciones y los comentarios de compromiso son difíciles de conseguir o podrían ser bastante antiguos.
Si la solución fue simple, es posible que no necesite un marcador de error. Si no es obvio, puede tener más sentido referirse a un error y luego escribir una explicación larga en una sección de comentarios.
Yo no hago eso. No puedo pensar en una buena razón por la que pondría la identificación del defecto en el código. Lo pondré en las notas de la versión / changelog en su lugar.
Lo que sí encuentro útil es usar el ID del defecto como parte del nombre en las pruebas automatizadas:
[TestFixture]
public class Release_1_2_Bugfixes
{
[Test]
public void TestBug42()
{
Assert.AreEqual(42, CalculateAnswerToLifeUniverseAndEverything());
}
}
He visto otros proyectos haciendo lo mismo.