comments - toluca - grupo didi ciudad de méxico cdmx
¿Utiliza comentarios especiales sobre correcciones de errores en su código? (21)
Algunos de mis colegas usan comentarios especiales sobre las correcciones de errores, por ejemplo:
// 2008-09-23 John Doe - bug 12345
// <short description>
¿Esto tiene sentido?
¿Comenta correcciones de errores de una manera especial?
Por favor hagamelo saber.
A menudo, un comentario como ese 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 su 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".
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 a 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.
Comentarios como este son los motivos por los cuales 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.
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.
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 se diseñó correctamente. Ocasionalmente, tengo que trabajar en una interfaz pública que no puede cambiar, por lo que esta suele 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 mensaje de confirmación de control de origen es lo que uso para anotar el cambio.
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 vez de esto:
// $ DATE $ NAME $ TICKET // comentario útil para la próxima pobre alma
Yo haría esto:
// comentario útil para la próxima pobre alma
No incluyo 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é.
No, no, y odio tener graffiti como esa basura en 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.
No. Uso la subversión y siempre ingreso una descripción de mi motivación para realizar 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.
Solo mis dos centavos.
Normalmente agrego mi nombre, mi dirección de correo electrónico y la fecha, junto con una breve descripción de lo que cambié. Esto se debe a que como asesor a menudo arreglo el código de otras personas.
// Glenn F. Henriksen (<[email protected]) - 2008-09-23
// <Short description>
De esa forma, los propietarios del código, o las personas que vienen detrás de mí, pueden descubrir qué sucedió y pueden ponerse en contacto conmigo si es necesario.
(sí, lamentablemente, la mayoría de las veces no tienen control de fuente ... para cosas internas uso el seguimiento de TFS)
Para ubicar los comentarios específicos, usamos DKBUGBUG , lo que significa que el parche y el revisor de David Kelley pueden identificar fácilmente, por supuesto agregaremos Fecha y otro número de seguimiento de errores de VSTS, etc. junto con esto.
Si agrega comentarios como ese después de unos años de mantener el código, tendrá tantos comentarios de corrección de errores que no podrá 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 lo cambie porque él (o ella) piensa que complicaste las cosas por una buena razón.
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.
El código base en el que trabajo 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.
Si el código está en una plataforma en vivo, lejos del acceso directo al repositorio de control de origen, entonces agregaré comentarios para resaltar los cambios realizados como parte de la corrección de un error en el sistema en vivo.
De lo contrario, ningún mensaje que ingrese al registrarse debe contener toda la información que necesita.
aclamaciones,
Robar
Solo si la solución fue particularmente inteligente o difícil de entender.
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. por ejemplo, podría hacer algo como esto en Perforce:
[Bug-Id] Problema con el diálogo xyz. Se movió el código de dimensionamiento a abc y ahora se iniciará más tarde.
Luego, en mi rastreador de problemas, haré algo como:
Solucionado en la lista de cambios 1234.
Se movió el código de dimensionamiento a abc y ahora se iniciará más tarde.
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é.
No trabajo en proyectos de varias personas, pero a veces agrego comentarios sobre un cierto error a una prueba de unidad.
Recuerde, no existen los errores, solo las pruebas insuficientes.
Como hago todo el TDD posible (todo lo demás es un suicidio social, porque cualquier otro método te obligará a trabajar un sinfín de horas), raramente soluciono errores.
La mayoría de las veces agrego comentarios especiales como este al 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" no merecen ningún otro comentario.
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.
Ese estilo de comentarios es extremadamente valioso en un entorno de múltiples desarrolladores donde hay una gama de habilidades y / o conocimiento comercial entre los desarrolladores (por ejemplo, en todas partes).
Para el experimentado desarrollador experimentado, 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 sobre el comentario "Acabo de poner eso en el sistema de control de fuente":
Si no está en la fuente, no sucedió.
No puedo contar la cantidad de veces que se perdió el historial de los proyectos debido a la falta de experiencia con el software de control de origen, los modelos incorrectos de ramificación, etc. Solo hay un lugar donde no se puede perder el historial de cambios, y eso está en el archivo fuente.
Normalmente lo pongo allí primero, luego corté y pegué el mismo comentario cuando lo controlé.