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

15

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.

sarat
fuente
3
La verdadera pregunta es POR QUÉ lo hacen así. Este podría ser un procedimiento muy antiguo antes del control de origen.
@anderson: creo que no tienen una comprensión adecuada sobre el uso de clearcase cuando se introdujo. Así que esa práctica podría haber seguido más ...
sarat
considerado encontrar?
No diré que es una mala práctica. De todos modos, una de las medidas de calidad del software es el porcentaje de comentarios a través del código fuente.
Rudy

Respuestas:

27

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.

Dysaster
fuente
Excelente respuesta He agregado algunos puntos más a mi pregunta. Por favor verifique y actualice su respuesta. gracias. Por cierto, ¿podría ayudarme con comandos clearcase para obtener registros de confirmación de una rama específica?
sarat
@Sarath Me temo que nunca antes había usado ClearCase. Siéntase libre de usar el superusuario para preguntar. Estoy seguro de que hay muchas personas que están dispuestas a ayudar.
Dysaster
44
Los buenos rastreadores de errores como JIRA pueden buscar en los registros de confirmación de su SCM y extraer información para detectar errores. Solo piense que comete algo para un error, y el rastreador de errores agrega automáticamente una nota al informe de error que confirma que X se refirió al error.
@ Andersen - Gracias estamos usando JIRA. Pero necesito asegurarme de si está usando correctamente o no.
sarat
@ Thorbjørn Ah, lo tienes fácil. Tuve que hacerlo manualmente en el día con el combo CVS / Bugzilla (y más tarde SVN / Bugzilla). Agregue la referencia de corrección de errores a mi confirmación y agregue la referencia de confirmación a bugzilla. Proceso propenso a errores, y los desarrolladores tienden a olvidar uno u otro. Pero la información fue muy útil en varias ocasiones.
Dysaster
23

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.

Charles E. Grant
fuente
3
Convenido. Agregue este tipo de comentarios cuando agreguen un valor significativo. Sin embargo, no los hagas solo por girar un mango.
rapid_now
Agradable, esto apoya la idea de los comentarios que dicen "Por qué" hay algún código. Ver programmers.stackexchange.com/questions/1/…
Gabriel
Lo he hecho varias veces: código que, a primera vista, desafía completamente la lógica ("¿para qué es este código aquí?") Pero en realidad está ahí por una muy buena razón, por lo que quieres que la gente lo lea con cuidado eso. Luego, agregar un comentario de advertencia que explique por qué ese código puede facilitar la vida de todos. Entonces, si alguien puede pensar en una mejor manera de resolver el problema original, todo el crédito para ellos, digo: saben por qué se implementó el código Braindead y qué se supone que debe lograr, por lo que es mucho más fácil implementar una alternativa solución.
un CVn
9

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.

Craig
fuente
3

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.

fejd
fuente
Esta es una falsa dicotomía. ¿Por qué no puede tener comentarios de diseño ("es por eso que hicimos xy z") cuando es necesario y mencionar identificadores de errores en los mensajes de confirmación?
Matthew Flaschen
¿Dónde dice que no puedes? Me refería a las identificaciones de errores en el código, no a los mensajes de confirmación de VCS.
febrero
Lo siento, he entendido mal. Pensé que estabas diciendo que no era útil poner identificadores de error en ningún lado.
Matthew Flaschen
No hay problema, eso solo significa que mi respuesta no fue lo suficientemente clara. :)
febrero
2

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.

refro
fuente
Supongo que el código comentado debería ser revisado por el SCM y se negó incluso a comprometerse ... Está agregando desorden al código solo por ganar 5 minutos de búsqueda en el historial de SCM si algún día hipotético en el futuro lo necesita espalda.
Julien Roncaglia
De acuerdo, pero intente implementar eso de manera segura: D En nuestro equipo de proyecto hemos estado trabajando con revisiones, por lo que por ahora el revisor rechaza esos bloques.
refro
Oh SourceSafe ... lo siento por ti y tu equipo.
Julien Roncaglia
No seas, es mejor que nada. Y en este momento todo el nuevo desarrollo se realiza con Subversion, por lo que cada mes tengo menos que ver con fuentes seguras.
refro
1

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.

Ben Hocking
fuente
1

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.

Matthew Flaschen
fuente