Algunos de mis colegas utilizan los comentarios especiales en sus correcciones de errores, por ejemplo:¿Utiliza comentarios especiales sobre correcciones de errores en su código?
// 2008-09-23 John Doe - bug 12345
// <short description>
¿Tiene esto sentido?
¿Comenta correcciones de errores de una manera especial?
Háganme saber.
No publico comentarios como ese, el sistema de control de fuente ya mantiene ese historial y ya puedo registrar el historial de un archivo.
Pongo comentarios que describen por qué algo no obvio se está haciendo. Entonces, si la corrección de errores hace que el código sea menos predecible y claro, entonces explico por qué.
Solo si la solución fue particularmente inteligente o difícil de entender.
Comentarios como este son los motivos por los que Subversion te permite escribir una entrada de registro en cada confirmación. Ahí es donde deberías poner estas cosas, no en el código.
Con el tiempo, estos pueden acumularse y agregar desorden. Es mejor dejar en claro el código, agregar comentarios para los errores relacionados que puedan no ser obvios y mantener los detalles del error en el sistema de seguimiento y el repositorio.
Aunque tiendo a ver algunos comentarios sobre errores dentro del código en el trabajo, mi preferencia personal es vincular un código de compromiso con un error. Cuando digo uno, realmente me refiero a un error. Después, siempre puede ver los cambios realizados y saber a qué error se aplicaron.
Para localizar los comentarios específicos que utilizamos DKBUGBUG - lo que significa solución y revisor de David Kelley podemos fácilmente identidad, Por supuesto vamos a añadir otra fecha y número de seguimiento de errores VSTS etc, junto con esto.
Tiendo a no hacer comentarios en la fuente real porque puede ser difícil mantenerse al día. Sin embargo, pongo comentarios de enlace en mi registro de control de fuente y en el rastreador de problemas. p.ej. Podría hacer algo como esto en Perforce:
[Error-Id] Problema con el diálogo xyz. Se cambió el código de tamaño a abc y ahora se inicializa el más tarde.
Luego, en mi seguimiento de incidencias voy a hacer algo como:
fijo en lista de cambios 1234.
Movido dimensionamiento código para ABC y ahora de inicialización después.
Porque entonces queda un buen marcador histórico. También hace que sea fácil si quieres saber por qué una determinada línea de código es de cierta manera, simplemente puedes mirar el historial del archivo. Una vez que haya encontrado la línea de código, puede leer mi comentario de compromiso y ver claramente para qué error fue y cómo lo arreglé.
Normalmente agrego mi nombre, mi dirección de correo electrónico y la fecha junto con una breve descripción de lo que cambié, es porque como consultor a menudo corrijo el código de otras personas.
// Glenn F. Henriksen (<[email protected]) - 2008-09-23
// <Short description>
De esa manera los responsables de códigos, o la gente que viene después de mí, pueden averiguar lo que pasó y que pueden ponerse en contacto conmigo si tienen que hacerlo.
(sí, por desgracia, más a menudo que no tienen ningún control de la fuente ... para cosas internas que utilizar el seguimiento de TFS)
Sourcecontrol realiza un seguimiento de toda esta información. Y, dado que usted es un consultor, debe consultar a su cliente para usar un sistema de control de fuente. –
Consulto lejos, pero a veces mi consejo cae en saco roto. Si el cliente tiene control de fuente nunca pongo esos comentarios, entonces es solo un ruido extra. – henriksen
¿Qué es el sistema de control de fuente? –
No, no lo hago, y no me gusta tener el graffiti como que ensucian el código. Los números de error se pueden rastrear en el mensaje de confirmación al sistema de control de versiones, y mediante scripts para enviar mensajes de confirmación relevantes al sistema de seguimiento de errores. No creo que pertenezcan al código fuente, donde las ediciones futuras simplemente confundirán las cosas.
Si bien esto puede parecer una buena idea en ese momento, rápidamente se sale de control. Tal información se puede capturar mejor usando una buena combinación de sistema de control de fuente y rastreador de errores. Por supuesto, si hay algo complicado pasando, un comentario que describa la situación sería útil en cualquier caso, pero no la fecha, el nombre o el número de error.
La base de código en la que estoy trabajando actualmente en el trabajo es algo así como 20 años y parece que han agregado muchos comentarios como este hace años. Afortunadamente, dejaron de hacerlo unos años después de que convirtieron todo a CVS a fines de los 90. Sin embargo, tales comentarios todavía están dispersos en todo el código y la política ahora es "eliminarlos si está trabajando directamente en ese código, pero de lo contrario, déjelos". A menudo son realmente difíciles de seguir, especialmente si se agrega y elimina el mismo código varias veces (sí, sucede). Tampoco contienen la fecha, pero contienen el número de error que tendrías que buscar en un sistema arcaico para encontrar la fecha, por lo que nadie lo hace.
No duplique los metadatos que su VCS guardará para usted. Las fechas y los nombres deben estar en el agregado automático del VCS. Los números de boletos, los nombres de administrador/usuario que solicitaron el cambio, etc. deben estar en los comentarios de VCS, no en el código.
En lugar de esto:
// $ $ FECHA NOMBRE DE ENTRADAS $ // comentario útil a la siguiente pobre alma
Me gustaría hacer esto:
comentario// útil para la próxima alma pobre
Lo hago si la corrección de errores involucra algo que no es sencillo, pero la mayoría de las veces si la corrección de errores requiere una explicación larga, lo tomo como una señal de que la solución no fue diseñada correctamente. De vez en cuando tengo que trabajar en torno a una interfaz pública que no puede cambiar lo que este tiende a ser la fuente de este tipo de comentarios, por ejemplo:
// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but
// some customers want the behavior. Jump through some hoops to find a default value.
En otros casos, el control de la fuente mensaje de consignación es lo que uso para anota el cambio.
A menudo un comentario como este es más confuso, ya que realmente no tiene contexto en cuanto a cómo se veía el código original, o el mal comportamiento original.
En general, si la corrección de errores ahora hace que el código se ejecute CORRECTAMENTE, simplemente déjelo sin comentarios. No hay necesidad de comentar el código correcto.
A veces la corrección de errores hace que las cosas parezcan extrañas, o la corrección de errores está probando algo que está fuera de lo común. Entonces podría ser apropiado hacer un comentario; por lo general, el comentario debería referirse al "número de error" de su base de datos de errores.Por ejemplo, es posible que tenga un comentario que diga "Error 123: tenga en cuenta el comportamiento extraño cuando el usuario tenga una resolución de pantalla de 640 por 480".
Ese estilo de comentarios es extremadamente valioso en un entorno de múltiples desarrolladores en el que hay una variedad de habilidades y/o conocimiento comercial entre los desarrolladores (por ejemplo, en todas partes).
Para el desarrollador experimentado con experiencia, el motivo de un cambio puede ser obvio, pero para los desarrolladores más nuevos que comenten les hará pensar dos veces y hacer más investigación antes de jugar con él. También les ayuda a aprender más sobre cómo funciona el sistema.
Ah, y una nota de la experiencia de los "que acabo de cargar en el sistema de control de código fuente" comentarios:
Si no está en la fuente, que no sucedió.
No puedo contar el número de veces que la historia de fuente para los proyectos se ha perdido debido a la falta de experiencia con el software de control de código fuente, los modelos de ramificación impropias etc. Hay solo lugar el historial de cambios no puede perderse - y eso está en el archivo fuente.
por lo general lo puso allí en primer lugar, a continuación, cortar 'n pegar el mismo comentario cuando lo compruebe en.
No estoy de acuerdo aquí. ¿Qué sucede cuando refactorizas este método? Tiene sentido eliminar el comentario también. –
Claro, borrar el código anterior y los comentarios asociados está bien. Es la parte de solo poner sus comentarios en un sistema externo que puede perderlos por usted mientras que todavía son válidos. No estoy de acuerdo. :-) –
Copia de seguridad. Apoyo. ¿Apoyo? – InsertNickHere
Si añade comentarios como que después de unos años de mantener el código que tendrá tantos corrección de errores comentarios que no podrías leer el código.
Pero si cambia algo que se ve bien (pero tiene un error sutil) en algo que es más complicado, es bueno agregar un breve comentario explicando lo que hizo, para que el siguiente programador en mantener este código no cambie vuelve porque él (o ella) piensa que usted superó cosas complicadas sin una buena razón.
Si el código está en una plataforma en vivo, lejos del acceso directo al repositorio de control de código fuente, agregaré comentarios para resaltar los cambios realizados como parte de la corrección de un error en el sistema en vivo.
De lo contrario, no el mensaje que ingrese en el registro debe contener toda la información que necesita.
aplausos,
Rob
No. Yo uso la subversión y siempre introducir una descripción de mi motivación para cometer un cambio. Por lo general, no repito la solución en inglés, sino que resumo los cambios realizados.
He trabajado en una serie de proyectos en los que pusieron comentarios en el código cuando se realizaron correcciones de errores. Curiosamente, y probablemente no por casualidad, se trata de proyectos que no utilizaron ningún tipo de herramienta de control de origen o que recibieron el mandato de seguir este tipo de convenciones por mandato de la administración.
Honestamente, realmente no veo el valor de hacer esto para la mayoría de las situaciones. Si quiero saber qué cambió, veré el registro de subversión y el diff.
Sólo mis dos centavos.
Cuando realizo correcciones de errores/mejoras en bibliotecas/componentes de terceros, a menudo hago algunos comentarios. Esto hace que sea más fácil encontrar y mover los cambios si necesito usar una versión más nueva de la biblioteca/componente.
En mi propio código rara vez comentarios correcciones de errores.
No trabajo en proyectos de varias personas, pero a veces agrego comentarios sobre un cierto error a una prueba de unidad.
Recuerde, no hay errores, solo pruebas insuficientes.
Como hago tanto TDD como sea posible (todo lo demás es un suicidio social, porque cualquier otro método te obligará a trabajar un sinfín de horas), casi nunca corrijo errores.
mayoría de las veces añado observaciones especiales como éste para el código:
// I KNOW this may look strange to you, but I have to use
// this special implementation here - if you don't understand that,
// maybe you are the wrong person for the job.
suena duro, pero la mayoría de las personas que se hacen llamar "desarrolladores" merecen no hay otras observaciones.
Si se corrige el código, el comentario es inútil y nunca es interesante para nadie, solo ruido.
Si el error no se resuelve, el comentario es incorrecto. Entonces tiene sentido. :) Así que simplemente deja esos comentarios si realmente no resolvió el error.
Tienes toda la razón. Recuerdo un método en nuestro código, que parece consistir únicamente en correcciones de errores (¡con respecto al tipo de comentarios mencionados anteriormente)! –
¿Qué es un repositorio de sistema de seguimiento? –
Cuando mencioné "sistema de seguimiento y repositorio" me refería a dos cosas. Uno, un sistema de seguimiento de errores, como bugzilla o JIRA, donde puedes poner comentarios sobre un problema. Segundo, un repositorio de código fuente como SVN o Git donde puedes poner comentarios con commits. –