Por lo general, considero que tales comentarios son una mala práctica y creo que este tipo de información pertenece a los registros de confirmación de SCM. Simplemente hace que el código sea más difícil de leer en la mayoría de los casos.
Sin embargo , todavía a menudo hago algo como esto para tipos específicos de ediciones.
Caso 1 - Tareas
Si usa un IDE como Eclipse, Netbeans, Visual Studio (o tiene alguna forma de realizar búsquedas de texto en su base de código con cualquier otra cosa), tal vez su equipo use algunas "etiquetas de comentarios" o "etiquetas de tareas" específicas. En cuyo caso esto puede ser útil.
De vez en cuando, al revisar el código, agrego algo como lo siguiente:
// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla
o:
// FIXME: [2010-12-09 haylem] marking this for review because blablabla
Utilizo diferentes etiquetas de tareas personalizadas que puedo ver en Eclipse en la vista de tareas para esto, porque tener algo en los registros de confirmación es algo bueno pero no suficiente cuando un ejecutivo le pregunta en una reunión de revisión por qué se olvidó por completo la corrección de errores XY y se deslizó a través. Entonces, en asuntos urgentes o piezas de código realmente cuestionables, esto sirve como un recordatorio adicional (pero generalmente mantendré el comentario breve y revisaré los registros de confirmación porque ESO es para eso que está el recordatorio, así que no abarroto el código también mucho).
Caso 2 - Parches de Libs de terceros
Si mi producto necesita empaquetar un código de terceros como fuente (o biblioteca, pero reconstruido desde la fuente) porque necesitaba ser parcheado por alguna razón, documentamos el parche en un documento separado donde enumeramos esas "advertencias" para referencia futura, y el código fuente generalmente contendrá un comentario similar a:
// [PATCH_START:product_name]
// ... real code here ...
// [PATCH_END:product_name]
Caso 3 - Soluciones no obvias
Este es un poco más controvertido y más cercano a lo que pide su desarrollador senior.
En el producto en el que trabajo en este momento, a veces (definitivamente no es algo común) tenemos un comentario como:
// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ
Solo hacemos esto si la corrección de errores no es obvia y el código se lee de manera anormal. Este puede ser el caso de las peculiaridades del navegador, por ejemplo, o las oscuras correcciones de CSS que debe implementar solo porque hay un error de documento en un producto. Entonces, en general, lo vincularíamos a nuestro repositorio de problemas internos, que luego contendrá el razonamiento detallado detrás de la corrección de errores y los punteros a la documentación del error del producto externo (por ejemplo, un aviso de seguridad para un defecto bien conocido de Internet Explorer 6, o algo como eso).
Pero como se mencionó, es bastante raro. Y gracias a las etiquetas de tareas, podemos ejecutarlas regularmente y verificar si estas soluciones extrañas aún tienen sentido o pueden eliminarse gradualmente (por ejemplo, si dejamos de admitir el producto defectuoso que causa el error en primer lugar).
Esto solo en: un ejemplo de la vida real
En algunos casos, es mejor que nada :)
Acabo de encontrar una gran clase de cálculo estadístico en mi base de código, donde el comentario del encabezado tenía la forma de un registro de cambios con el yadda yadda habitual: revisor, fecha, ID de error.
Al principio pensé en eliminarlo, pero noté que las ID de errores no solo no coincidían con la convención de nuestro rastreador de problemas actual, sino que tampoco coincidían con el del rastreador utilizado antes de unirme a la empresa. Así que traté de leer el código y entender lo que estaba haciendo la clase (no ser estadístico) y también traté de desenterrar estos informes de defectos. Resulta que eran bastante importantes y habrían cambiado la vida del próximo tipo para editar el archivo sin saber sobre ellos bastante horrible, ya que se trataba de problemas menores de precisión y casos especiales basados en requisitos muy específicos emitidos por el cliente de origen en ese momento. . En pocas palabras, si estos no hubieran estado allí, no lo habría sabido. Si no hubieran estado allí Y yo hubiera tenido una mejor comprensión de la clase,
A veces es difícil hacer un seguimiento de requisitos muy antiguos como estos. Al final, lo que hice fue eliminar el encabezado, pero después de introducir un comentario en bloque antes de cada función incriminatoria que describe por qué estos cálculos "extraños" son solicitudes específicas.
Entonces, en ese caso, todavía consideraba que esto era una mala práctica, ¡pero estaba feliz de que el desarrollador original al menos los pusiera! Hubiera sido mejor comentar el código claramente en su lugar, pero supongo que fue mejor que nada.