¿El uso especial de los comentarios sobre las correcciones de errores en el código?
https://stackoverflow.com/questions/123936
-
02-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianPregunta
Algunos de mis colegas uso especial de los comentarios en sus correcciones de errores, por ejemplo:
// 2008-09-23 John Doe - bug 12345
// <short description>
¿Esto tiene sentido?
Comentarios correcciones de errores de una manera especial?
Por favor, hágamelo saber.
Solución
No pongo en comentarios como ese, el sistema de control de origen ya que mantiene la historia y ya soy capaz de registrar el historial de un archivo.
Pongo en comentarios que describen por qué algo que no es obvio que se está haciendo, aunque.Así que si la corrección de errores hace que el código sea menos predecible y claro, luego les explico por qué.
Otros consejos
Con el tiempo estos se pueden acumular y desordena.Es mejor hacer el código de borrar, agregar comentarios relacionados a problemas comunes que puede no ser evidente y mantener el error detalle en el sistema de seguimiento y repositorio.
Tiendo a no comentar en la fuente real porque puede ser difícil mantenerse al día.Sin embargo, que yo ponga la vinculación de los comentarios en mi fuente de control y de registro issue tracker.por ejemplo,Yo podría hacer algo como esto en Perforce:
[Error-Id] Problema con el teclado de diálogo.Movido de tamaño de código para abc y ahora llegará más tarde.
Luego, en mi issue tracker voy a hacer algo como:
Fijo en changelist 1234.
Movido de tamaño de código para abc y ahora llegará más tarde.
Porque entonces un buen marcador histórico está a la izquierda.También se hace fácil si usted quiere saber por qué una determinada línea de código es una cierta manera, usted puede buscar en el archivo de la historia.Una vez que usted haya encontrado la línea de código, puedes leer mi comprometerse comentario y ver claramente el error es y cómo me fijo.
Sólo si la solución fue particularmente inteligente o difícil de entender.
Yo suelo añadir mi nombre, mi dirección de correo electrónico y la fecha, junto con una breve descripción de lo que ha cambiado, Eso es porque como consultor a menudo me revisión de otras personas de código.
// Glenn F. Henriksen (<email@company.no) - 2008-09-23
// <Short description>
De esa manera el código de propietarios, o la gente que viene después de mí, se puede averiguar lo que pasó y que puede ponerse en contacto conmigo si tienen que.
(sí, por desgracia, más a menudo que no tienen ningún control de código fuente...para la materia interna yo uso TFS de seguimiento)
Mientras que esto puede parecer una buena idea en el momento, rápidamente se sale de control.Dicha información puede ser mejor capturadas con una buena combinación de fuente y sistema de control de seguimiento de errores.Por supuesto, si hay algo complicado pasando, un comentario que describe la situación sería útil en cualquier caso, pero no la fecha, el nombre o el número del error.
La base de código, actualmente estoy trabajando en el trabajo es algo así como 20 años y parece que han añadido un montón de comentarios de este años.Por suerte, dejó de hacerlo hace un par de años después de haber convertido todo a CVS en el finales de los 90.Sin embargo, estas observaciones son aún cubrían todo el código y la política ahora es "quitar si usted está trabajando directamente en ese código, pero de otra manera de salir de ellos".Son a menudo muy difícil de seguir, especialmente si el mismo código se agregan y quitan varias veces (sí, que pasa).Además, no contienen la fecha, pero contiene el número de error que usted tendría que ir a buscar en un arcaico sistema para averiguar la fecha, por lo que nadie hace.
Comentarios como este son la razón por la Subversion permite escribir una entrada de registro en cada confirmación.Que es donde debe colocar este material, no en el código.
Yo lo hago si la corrección del error de la trata de algo que no es sencillo, pero más a menudo que no, si la corrección de errores requiere de una larga explicación me lo tomo como un signo de que la revisión no fue diseñado así.Tengo de vez en cuando para evitar una interfaz pública que no se pueden cambiar así que esto tiende a ser la fuente de estos tipos 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 código fuente del mensaje de confirmación es lo que yo uso para anotar el cambio.
Mientras que tiendo a ver algunos comentarios sobre errores dentro del código del trabajo, mi preferencia personal es la vinculación de un código a cometer un error.Cuando digo uno que realmente me refiero a un error.Después de que usted puede mirar siempre los cambios realizados y saber que bicho de estos se aplicaron.
Que estilo de comentario es muy valioso en un multi-entorno de desarrollo, donde hay una serie de habilidades y / o conocimientos de negocio a través de los desarrolladores (por ejemplo,- en todas partes).
Para el experimentado experto desarrollador de la razón para un cambio que puede ser obvio, pero para los nuevos desarrolladores que comentar les hará pensar dos veces y hacer más investigación antes de jugar con él.También les ayuda a aprender más acerca de cómo funciona el sistema.
Ah, y una nota de la experiencia sobre la "acabo de poner que en el sistema de control de origen" comentarios:
Si no está en la fuente, no sucedió.
No puedo contar el número de veces que el origen de la historia de los proyectos se ha perdido debido a la inexperiencia con el software de control de origen, inadecuado modelos de ramificación etc.Hay sólo hay un lugar donde el cambio de la historia no se puede perder - y eso es en el archivo de origen.
Yo suelo ponerlo allí en primer lugar, a continuación, cut 'n pegar el mismo comentario cuando me registre.
No, yo No, y no me gusta tener el graffiti como que la basura el código.Números de fallo pueden ser rastreados en el mensaje de confirmación para el sistema de control de versiones, y por scripts para empujar relevantes de mensajes de confirmación en el sistema de seguimiento de errores.No creo que pertenecen en el código fuente, donde el futuro de ediciones acaba de confundir las cosas.
A menudo, un comentario como el que es más confuso, ya que en realidad no tiene como contexto para lo que el código original como parecía, o el original de mal comportamiento.
En general, si su corrección de errores ahora hace que el código se ejecute CORRECTAMENTE, simplemente dejarlo sin comentarios.No hay necesidad de comentar el código correcto.
A veces la corrección de errores hace que las cosas se ven de raro, o la corrección de errores es la prueba de algo que está fuera de lo común.Entonces sería apropiado tener un comentario - generalmente el comentario debería referirse a la "número de error" de su base de datos de errores.Por ejemplo, usted podría tener un comentario que dice "Error 123 - dan Cuenta de un comportamiento extraño cuando el usuario está en 640 por 480 de resolución de pantalla".
Si usted agregar comentarios como que después de un par de años de mantener el código, usted tendrá muchas corrección de error en los comentarios que usted no sería capaz de leer el código.
Pero si cambiar algo de lo que mira a la derecha (pero tienen un error sutil) en algo que es más complicado de lo que es bueno añadir un breve comentario explicando lo que hizo, así que la próxima programador para mantener este código no cambia de nuevo, porque él (o ella) piensa que el exceso de cosas complicadas por ninguna buena razón.
No.Yo uso la subversión y siempre escriba una descripción de mi motivación para cometer un cambio.Generalmente no me diga la solución en inglés, en lugar de un resumen de los cambios realizados.
He trabajado en una serie de proyectos donde poner comentarios en el código cuando correcciones de errores se hicieron.Curiosamente, y probablemente no por casualidad, estos fueron los proyectos que no se use ningún tipo de control de código fuente de la herramienta o fueron obligados a seguir este tipo de convenio por parte de fiat de gestión.
Sinceramente, yo no veo el valor de hacer esto para la mayoría de las situaciones.Si quiero saber lo que ha cambiado, voy a mirar a la subversión y el registro de las diferencias.
Sólo mis dos centavos.
Si el código se ha corregido, el comentario es inútil y nunca interesantes a nadie - sólo ruido.
Si el error no se soluciona, el comentario está mal.Entonces tiene sentido.:) Así que deje comentarios si usted en realidad no se resuelve el error.
Para buscar más específicas comentario utilizamos DKBUGBUG - lo que significa que David Kelley revisión y revisor puede fácilmente identidad, por supuesto, vamos a añadir la Fecha y otros VSTS de seguimiento de fallos número de etc, junto con este.
No duplicar datos de metadatos que su VCS se va a mantener para usted.Las fechas y los nombres deben estar en el añadido automáticamente por el VCS.Los números de los boletos, el administrador/nombres de usuario que solicitó el cambio, etc debe ser en VCS comentarios, no el código.
En lugar de esto:
//$FECHA $NOMBRE $DE ENTRADAS //comentario útil para la próxima pobre alma
Yo haría esto:
//comentario útil para la próxima pobre alma
Si el código está en una plataforma real, lejos de acceso directo al repositorio de control de origen, a continuación voy a añadir comentarios para resaltar los cambios realizados como parte de la solución a un error en el sistema en vivo.
De lo contrario, no el mensaje de que usted introduzca en el checkin debe contener toda la información que necesita.
saludos,
Rob
Cuando hago correcciones/mejoras en las bibliotecas de terceros/componente a menudo me hacen algunos comentarios.Esto hace que sea más fácil encontrar y mover los cambios si tengo que usar una versión más reciente de la biblioteca/componente.
En mi propio código pongo comentarios, correcciones de errores.
Yo no trabajo en múltiples proyectos de persona, pero a veces me agregar comentarios sobre un cierto error en una unidad de prueba.
Recuerde, no hay tal cosa como los insectos, sólo pruebas insuficientes.
Ya que yo como mucho TDD como sea posible (todo lo demás es el suicidio social, porque todos los demás métodos se te obligan a trabajar horas interminables), yo raramente la corrección de errores.
La mayoría del tiempo he agregar comentarios especiales como esta 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 feo, pero la mayoría de la gente que se llaman a sí mismos "desarrolladores" no se merecen otras observaciones.
