¿Es bueno mantener los comentarios de corrección de errores dentro del código?

Mi equipo está utilizando el caso claro como control de versión. El proyecto en el que estoy trabajando no se inició hace 7-8 años. Durante todo el tiempo de vida del proyecto, tuvimos varios lanzamientos de paquetes de servicio de corrección de errores, etc. Los problemas se rastrean utilizando el sistema de seguimiento de errores y la mayoría de las personas que trabajan en las soluciones de errores siguen una rutina de incluir el comentario en START / FIN de bloque con la fecha, autor, identificación de error, etc.

Creo que esto es bastante irrelevante y hace que el código esté desordenado y difícil de mantener, y estas son las cosas que deben ser parte de los comentarios / etiquetas de check-in, etc., donde podemos mantener información adicional del ciclo de vida del producto de trabajo.

¿Cuál es la mejor práctica a seguir?

Algunos de los revisores del código insisten en publicar los comentarios sobre el error y las correcciones para facilitar su vida. Según tengo entendido, deben revisar los archivos asignándolos a una vista y obtener el registro de cambios de la rama y revisarlo. Sería útil si puedo obtener algunas prácticas recomendadas para enviar el código actualizado para su revisión.

El problema al agregar la corrección de errores como un comentario al código es que no obtienes la historia completa. Si veo una pieza perfectamente bien de código de etiqueta "se trata de una solución al error , bla ", mi primera reacción sería decir "¿y qué?". El código está ahí, funciona. Lo único que necesito saber para mantener el código es un comentario que me dice qué hace.

Una mejor práctica sería agregar referencias de corrección de errores en los registros de confirmación de SCM. De esa manera, verá cuál es el error, dónde se introdujo y cómo se solucionó. Además, cuando llega el momento de una versión, simplemente puede extraer los registros de SCM y agregar un punto de viñeta que indique que hubo un error y que se solucionó. Si otra rama o versión introduce el mismo error, es fácil localizar la solución y volver a aplicarla si es lo mismo.

Habiendo dicho todo esto, también estoy de acuerdo con la respuesta de Charles. Si el motivo de un fragmento de código no es obvio, dígale al responsable de mantenimiento que el código está ahí por un motivo y debe tratarse con cuidado.

Principalmente mala práctica. No diré que nunca debería hacerse. De vez en cuando te encuentras con algo así como un error en una API externa con la que tienes que solucionar. La solución puede parecer completamente mortal si no conoce el error subyacente. En ese caso, puede ser una buena idea documentar el error en el código para que los compañeros de trabajo o usted mismo no intenten "arreglar" el código que obviamente no funciona.

Mala práctica. Los comentarios se desactualizarán y desordenarán el código. La información aún está disponible en el historial de versiones de su sistema SCC si es necesario.

Suena como una mala práctica. ¿Qué sucede si su organización decide migrar a otro sistema de seguimiento de errores? No ate demasiado su producto a las herramientas que está utilizando actualmente. En lugar de referirse a ID de errores específicos, y las razones por las cuales el código parece no estar claro, motive su decisión de diseño con comentarios en el código.

Mi primera reacción sería no repetirlo, así que sáquelo del código y póngalo en los registros de SCM. Hemos tenido una discusión similar aquí sobre comentarios de revisión para funciones, nombres de autores y fechas de creación de archivos y funciones. En el pasado (antes de usar SCM), toda esta información se guardaba en los archivos para poder reconstruir la evolución de un archivo.

Aproximadamente la mitad de los desarrolladores desean que esta información pueda tener toda la información en un solo lugar (esto los activa para buscar cambios en el SCM). La otra mitad de los desarrolladores no comienzan su búsqueda de pistas sobre lo que cambió en el coeficiente, sino desde SCM, por lo que no necesitan la información en el código. Todavía tenemos que tomar una decisión sobre qué hacer con esos comentarios. Depende mucho de la forma en que las personas trabajan y algunas personas son muy tercas al abandonar sus métodos conocidos. Lo mismo sobre comentar el bloque de código y dejarlos en el código para siempre.

Solo para agregar a lo que Dyaster et al. Dicho esto, aunque JIRA tiene habilidades realmente buenas para mostrar los cambios asociados con las correcciones de errores, el mejor lugar absoluto para documentar una corrección de errores es en un caso de prueba. Si el código no está claro sin un comentario que indique qué error se corrigió, eso es "olor a código". Dicho esto, si no tiene tiempo para limpiar el olor, el comentario debe referirse al caso de prueba, donde debería ser mucho más obvio por qué el código está haciendo lo que está haciendo. Si no tiene tiempo para escribir un caso de prueba que explique la corrección del error, entonces el error aún no se ha solucionado, solo se ha pospuesto.

Estoy de acuerdo con agregar identificadores de corrección de errores en los mensajes de confirmación, y no dentro del código en sí. Los rastreadores de errores que raspan automáticamente los mensajes de confirmación para identificadores de errores son muy útiles.

Además, puede usar el comando blame / annotate / elogio de su sistema de control de versiones para ayudar a reemplazar estos comentarios. Entonces, cuando ejecutas algo como:

vcs blame file.ext

puede ver información útil, que generalmente incluye quién cambió cada línea, cuándo la cambiaron y la identificación de confirmación. Desde la identificación de confirmación, puede obtener el mensaje completo, que debe incluir la identificación del error.

Los buenos sistemas VCS le permitirán ignorar los espacios en blanco al calcular quién modificó una línea.

No sé qué tiene Clear Case para esta función.