número de errores comenta

Question

Por qué añadirías

// Bug 1024

comentarios en una base de código fuente controlado? La mayoría de los sistemas de control de fuente y seguimiento de errores están mejor equipados para realizar un seguimiento de esta información. En 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 muy breve y tienden a acumular basura en la base del código.

Answer 1

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 del 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 voy a decir 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.

Answer 2

Pereza pura. 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.

Answer 3

En última instancia, 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.

Answer 4

Lo hice hasta Visual Studio 2008 enviado con la 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 las versiones anteriores, pero eso es un dolor en el trasero cuando solo necesitas un rápido sentirse bien acerca de las actualizaciones de códigos menores.

Answer 5

Imagine que tiene un nuevo error que rastrea al cambio en la revisión 12345. Mirar 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).

Answer 6

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 este caso, a cualquier repositorio de KM que pueda tener).

A veces 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 solución de error en particular lo hace visible durante el factoraje, 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.

P.S. podría considerar útil el artículo this 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.

Answer 7

Lo encuentro útil cuando explico un código que de otro modo parecería incorrecto, y también para usarlo en los mensajes de confirmación.

Answer 8

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.

Answer 9

Creo que este es un caso de "Tengo un martillo, que 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 origen.

Answer 10

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í parece útil es usar el defecto Id como parte del nombre en las pruebas automatizadas:

[TestFixture] 
public class Release_1_2_Bugfixes 
{ 
    [Test] 
    public void TestBug42() 
    { 
    Assert.AreEqual(42, CalculateAnswerToLifeUniverseAndEverything()); 
    } 
} 

que he visto other projects haciendo lo mismo.

Answer 11

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 (con suerte también parafraseará los bits importantes del error) , sin embargo).

Sí, los mensajes de confirmación de control de fuente también deben contener los números de error, y mirando 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 de la falla inicial aún se 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 cambiar el nombre de los archivos, lo que haría aún más difícil encontrar la raíz del motivo detrás de una determinada sección de código (no cambiar el nombre tanto de un problema con SVN, pero un dolor con CVS).

Answer 12

Nunca debe agregar solo el número de error. Debe agregar el número de error y el asunto, y cualquier calificador si realizó múltiples comprobaciones 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 error. 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.

Answer 13

Le pegaste 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 de origen los hace un poco menos legibles y difíciles de mantener. Elimina todo lo que no agrega valor. "Bug 12345" tiene poco valor ahora, y no tendrá ninguno en unas pocas semanas.

Answer 14

Trabajamos en un sistema a gran escala con muchos desarrolladores y múltiples ramas liberadas.

Estos comentarios de referencia de error realmente pueden ser muy útiles durante la transferencia de una rama a otra, especialmente porque el sistema SCM que utilizamos es muy pobre y los comentarios de compromiso son difíciles de conseguir o podrían ser bastante antiguos.

Si la solución es simple, es posible que no necesite un marcador de error. Si no es obvio, puede tener más sentido hacer referencia a un error y luego escribir una explicación larga en una sección de comentarios.

Answer 15

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 corrigen errores que se superponen con una corrección de error anterior. Luego tiene números de error que etiquetan una sección de código que simplemente es incorrecta o engañosa.

Answer 16

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 solo es obvio en un proyecto anterior con historial y una gran cantidad de correcciones de errores previas. 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 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.

EDIT: 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 realice :-)

Answer 17

Este tipo de comentarios IS muy útil: ¿qué ocurre 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).

Answer 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 de los clientes 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.