¿Está bien poner comentarios sobre correcciones de errores en el código fuente?

Question

Y si es así, ¿dónde dibujas la línea? Mis compañeros de trabajo y yo no estamos de acuerdo en este tema. He visto cosas tales como

// fixes bug # 22 

a

// fixed bug: shouldnt be decrementing 
i++; 

¿Está bien si el cambio es bastante significativo, lo que cambia radicalmente el método fue escrito para hacer? ¿O simplemente cambia el texto resumido del método para reflejar lo que ahora debe hacer?

Mi opinión es que esta información debe ponerse en control de la fuente. Algunos afirman que esto es malo porque luego se perderá fuera del contexto del control de la fuente (digamos que cambias los sistemas y deseas conservar los datos históricos).

Answer 1

Los comentarios deberían explicar cómo funcionan los métodos.

El control de fuente explica por qué se realizaron cambios.

Answer 2

Tuvimos algunos comentarios como este, pero luego nuestro servidor Bugzilla murió y reiniciamos en el error # 1, así que no tienen sentido. Una breve explicación del error es mi método preferido ahora.

Answer 3

comentarios Suponiendo que no son superfluas (i++; //increment i el ejemplo clásico viene a la mente), casi nunca hay una razón para argumentar en contra añadir un comentario, independientemente de lo que está relacionado con. La información es útil. Sin embargo, es mejor ser descriptivo y conciso: no digas "corrige errores # YY", sino que agrega algo como "esto solía fallar para x = 0, la lógica extra aquí lo impide". De esa manera, alguien que mira el código más tarde puede entender por qué una sección en particular es crítica para el funcionamiento correcto.

Answer 4

No. Debe mantener la información sobre los errores y el conjunto de cambios que corrige el error externo al código fuente. Cualquier comentario en el código en sí solo debe relacionarse con lo que está haciendo el código. Cualquier otra cosa es solo desorden.

Answer 5

Personalmente creo que los comentarios deberían ser sobre el código en sí, no sobre una corrección de errores.

Mi razón para esto es la capacidad de mantenimiento - 2 (o 10) años después, este comentario ya no será significativo. En el ejemplo anterior, yo preferiría algo así como:

// Increment i to counteract extra decrement 
++i; 

La diferencia es que no está atado a un error, sino más bien lo que el código está haciendo. Los comentarios deberían estar comentando el código, no la meta información, la OMI.

Esta opinión es parcialmente porque mantener una base de código muy antiguo - y tenemos un montón de comentarios que ya no están significativa relacionada correcciones de errores y solicitudes de mejora de funciones, etc ....

Answer 6

me baso en FogBugz y comentarios de check-in en svn. Funciona muy bien, aunque como dijo Jeffamaphone, los números de caso no tienen mucho sentido si pierdes tu base de datos de errores.

Un problema al poner comentarios en el código es que, con el tiempo, su código se llenará de comentarios sobre problemas que no han existido por un tiempo. Al colocar dichos comentarios en los comentarios de control de origen, está efectivamente vinculando la información sobre el arreglo a la versión específica donde fue corregida, lo cual puede ser útil más adelante.

Answer 7

Mi opinión es que los comentarios deben ser relevantes para la intención del desarrollador, o los aspectos más destacados del "por qué" que rodea el algoritmo/método.

Los comentarios no deben rodear a un arreglo en el tiempo.

Answer 8

Agregar un comentario sobre la corrección de errores es una buena idea, si escribe lo correcto.

Por ejemplo,

/* I know this looks wrong, but originally foo was being decremented here, and 
    it caused the baz to sproing. Remember, the logic is negated by blort! */ 

Cosas como Fixes bug #22es mejor guardado de control de origen. Los comentarios en su código deben ser indicadores para ayudar a los futuros viajeros en su camino, no para satisfacer el proceso y el seguimiento.

Answer 9

Acepto que dichos datos se deben colocar en el control de la fuente u otra parte Configuration Management. Después de haber trabajado en las bases de código que colocan información sobre correcciones de errores en los comentarios, puedo decir que lleva a comentarios y códigos muy desordenados más adelante. Seis meses después de que la solución esté en su lugar, ¿de verdad quieres saber eso sobre una línea que arregle algún error de hace mucho tiempo? ¿Qué haces con los comentarios cuando necesitas refactorizar el código?

Answer 10

Algo como // fixes bug # 22 es bastante insignificante por sí solo, y requiere pasos adicionales para incluso hacerse una idea de lo que significa y qué papel cumple. Una breve descripción es, en mi opinión, más apropiada, independientemente del seguimiento de errores o del software de control de origen que pueda estar utilizando.

Answer 11

Si el algoritmo necesita ser codificado de cierta manera - para solucionar un error en una API de terceros, por ejemplo, entonces eso debe comentarse en el código para que la siguiente persona que venga no intente " optimizar "el código (o lo que sea) y reintroducir un problema.

Si esto implica agregar un comentario cuando arregla el error original, hágalo.

También servirá como marcador para que pueda encontrar el código que necesita comprobar si alguna vez actualiza a la próxima versión de la API.

Answer 12

Utilizamos Team Foundation Server para el control de código fuente aquí en mi empresa y le permite vincular un check-in a un informe de error, por lo que no pondría un comentario directamente en el código del servidor con el mismo propósito.

Sin embargo, en situaciones donde estoy implementando código como una solución para un error en .NET framework o en una biblioteca de terceros, me gusta poner una URL en el registro o sitio web de Microsoft TechNet que describe el error y su estado.

Answer 13

Así que, obviamente

// fix bug #22 
    i++; 

no es una comunicación eficaz.

La buena comunicación es principalmente sentido común. Di lo que quieres decir.

// Compensate for removeFrob() decrementing i. 
    i++; 

Incluya el número de error si parece que puede ayudar a los lectores futuros.

// Skipping the next flange is necessary to maintain the loop 
    // invariant if the lookup fails (bug #22). 
    i++; 

En ocasiones, las conversaciones importantes se registran en el sistema de seguimiento de errores. A veces, un error conduce a una percepción clave que cambia la forma del código.

// Treat this as a bleet. Misnomed grotzjammers and particle 
    // bleets are actually both special cases of the same 
    // situation; see Anna's analysis in bug #22. 
    i++; 

Answer 14

En el repositorio de fuentes Perl5 es común referirse a los insectos, con su número de asociado Trac en los archivos de prueba.

Esto tiene más sentido para mí, porque agregar una prueba para un error evitará que ese error vuelva a pasar desapercibido.