Número de error de comentarios
https://stackoverflow.com/questions/163232
-
03-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianPregunta
¿Por qué agregarías
// Bug 1024
¿comentarios en una base de código controlada por fuente? La mayoría de los sistemas de seguimiento de errores y control de fuente están mejor equipados para realizar un seguimiento de esta información. En el control de código fuente, se puede usar una etiqueta o comentario con el registro. 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, ya que la relevancia de estos comentarios es muy breve y tienden a acumularse en la base del código.
Solución
El otro día encontré uno de estos útiles en nuestro código base.
Dije " ¿por qué está llamando a la función de inicialización por segunda vez, esta tarde en el flujo de trabajo? "
El comentario de error me dejó ir directamente a la descripción del problema. Cuando actualicé el código, me aseguré de incluir ese error en mis pruebas y no lo volví a introducir.
Aunque diré que, en general, estoy de acuerdo con usted y no lo inserto yo mismo.
Habría preferido que el desarrollador en cuestión solucionara el error de una manera más significativa, para que no tuviera que preguntarme sobre el código en primer lugar.
Otros consejos
En última instancia, creo que es una mala práctica. Es mejor incluir por qué existe el error (los servidores de tipo Y no tienen la propiedad Z). Puede incluir un " más en BugId 12345 " junto con eso si quieres.
Si se está integrando en múltiples niveles, una vista de código fuente en trac puede vincularse directamente al BugId.
Pura pereza. Claro, lleva más tiempo a largo plazo, pero a corto plazo " // Error 1024 " no toma ningún esfuerzo en absoluto. Cuanto más código tengas, peor es esto.
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 que se realizó el cambio.
Luego puedes ir y mirar 1024 para ver qué, por qué y cuándo, antes de hacer una nueva solución: el 'uno para gobernarlos a todos'.
Si el número de error no se encuentra en el mensaje de confirmación, debe buscar el error que se corrigió, y puede haber varios (si se informa el error más de una vez).
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 debe describirse en los comentarios cuando no sean inmediatamente obvios.
Estoy de acuerdo en que los números de error deben estar en los mensajes de confirmación de control de origen.
Nunca debes agregar solo el número de error. Debe agregar el número de error y el asunto, y cualquier calificador, si realizó varios registros para un solo error:
Error 1111 - Foo roto en sistemas de 64 bits. Arreglo # 2 porque se volvió a abrir después de la fusión al enlace troncal.
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 de bugzilla.mozilla.org. Cuando está introduciendo el código, esto supone un gran ahorro de tiempo. Creo que Fogbugz tiene una característica similar ...
Además, incluso si su sistema no lo hace, a menudo es útil porque nadie quiere ver todo el contexto del cambio en los comentarios, para eso está el rastreador de errores.
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 que se extienden a cualquier repositorio de KM que pueda tener).
A veces, se cambia un código para implementar una solución a un determinado problema con el comportamiento de la aplicación. A veces, la solución introducida no es de ninguna manera lógica. A menudo sucede que cuando alguien actualiza un código, esta parte "mala" del código se elimina como parte del esfuerzo de re-factorización.
Por lo tanto, marcar un código como perteneciente a una solución de error en particular lo hace visible durante la re-factorización, lo que solicita al desarrollador que revise la descripción del error antes de cambiar el código. También ayuda en la situación en la que se vuelve a abrir el error: si tiene que cambiar la misma parte del código varias veces, podría considerar invertir tiempo en una solución alternativa.
P.S. puede considerar este artículo sobre MS Office de Joel On Software útil. Por lo que sé, el código de MS Office y MS Windows está lleno de comentarios similares que explican las decisiones tomadas por los desarrolladores hace mucho tiempo.
Me resulta útil cuando se explica el código que de otro modo parecería incorrecto, y también para el uso en mensajes de confirmación.
Yo no hago eso. No puedo pensar en una buena razón por la que pondría el ID de defecto en el código. Pondré eso en las notas de lanzamiento / changelog en su lugar.
Lo que sí encuentro útil es usar el Id. de 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.
Me sorprende la cantidad de personas que se oponen a esto. Mi opinión personal sobre esto es que son una muy buena idea . Estoy de acuerdo con un comentario anterior de 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 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á fragmentos de código que parecen ilógicos o innecesarios sin contexto.
Debido a las interacciones con el sistema o las soluciones provisionales, el código es necesario . Para evitar que alguien vuelva a introducir un error parcheado, es extremadamente útil 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 verifique cuidadosamente el historial de confirmación por un motivo registrado en el registro de confirmación, lo cual es muy poco probable, especialmente si alguien está refactorizando el código.
EDIT : me refiero específicamente a poner esto con un bloque de código que es inusual o que necesita el contexto adicional. No es útil ni necesario comentar cada una de las correcciones de errores tipográficos que realice :-)
Hice esto hasta que Visual Studio 2008 se envió con una anotación. Fue útil al mirar hacia atrás en el código antiguo para ver inmediatamente que al menos se pensó detrás de una decisión de código en particular.
Sí, sé que puedes hacer comparaciones con versiones anteriores, pero eso es un dolor en el trasero cuando solo necesitas una rápida sensación de las pequeñas actualizaciones de código.
Si estás navegando a través de un código fuente que no conoces, y ves algo obvio, es bueno saber la razón. Sin embargo, es una decisión de juicio, no todas las correcciones de errores necesitan tal explicación, probablemente la mayoría puede escapar sin ella.
Si hay razones suficientes para creer que alguien querría saber el número de error al mirar parte del código, agregar un comentario mencionando el error puede ser bastante bueno (con suerte, parafraseará también las partes importantes del error, sin embargo).
Sí, los mensajes de confirmación de control de origen también deben contener los números de error, y revisar los registros de revisión puede proporcionarle la misma información ... pero si la misma parte del código se cambia varias veces, pero los detalles aprendidos de la el error inicial aún se aplica, puede tomar un tiempo encontrar el cambio original para aprender sobre ese error.
También, las situaciones surgen 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 (el cambio de nombre no es tan mucho de un problema con SVN, pero un dolor con CVS).
Has golpeado el clavo en la cabeza con "la relevancia es muy breve y tienden a acumularse en la base del código". "
Cada bit de crucero inútil que se acumula en los archivos de origen hace que sean un poco menos legibles y difíciles de mantener. Eliminar todo lo que no agrega valor. " Error 12345 " tiene poco valor ahora y no lo tendrá en unas pocas semanas.
Trabajamos en un sistema a gran escala con muchos desarrolladores y múltiples sucursales liberadas.
Estos comentarios de referencia de errores en realidad pueden ser bastante útiles durante la transferencia de una rama a otra, especialmente porque el sistema SCM que utilizamos es muy deficiente en características y es difícil obtener comentarios o pueden 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.
No me gusta este tipo de graffiti. Al igual que otras formas de vida de mal gusto, se acumulan con el tiempo, ahogando el código base.
El problema realmente comienza cuando las personas hacen correcciones de errores que se superponen a una solución de error anterior. A continuación, tiene números de error que etiquetan una sección de código que es simplemente errónea o engañosa.
Este tipo de comentario ES es muy útil: ¿qué sucede cuando cambia las herramientas de seguimiento de errores o de control de fuente? Una referencia a BZ1722 vs FB3101 le indicaría qué herramienta de seguimiento debe verificar (Bugzilla o FogBugz, por ejemplo).
¡Es algo bueno!
Es poco probable que la persona que está mirando el código aprecie el historial completo del código y pueda deshacer un cambio muy importante porque es posible que no haya trabajado antes en esta área del código. Puede explicar el código que de otra manera parece una locura o un requisito del cliente que es equivalente de manera extraña.
No siempre se pueden capturar los detalles particulares 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 hackeas el código en el estúpido cuando te ves obligado a hacerlo, los números de error respaldan la intención del código loco.
