¿Actualizas los comentarios del código antiguo que son incorrectos?

Question

día G,

Inspirado por un comentario que hice en mi respuesta a this question al comentar las expresiones regulares de Perl Me preguntaba lo siguiente.

Cuando trabajas en código antiguo, viejo y sangriento antiguo, actualizas los comentarios que no están sincronizados con el código o simplemente actualizas el código e ignoras los comentarios que ya están "alejados" de la realidad del código actual?

Supongo que básicamente me estoy acercando a las cosas del síndrome "broken window"?

BWS básicamente dice que las personas simplemente dicen "cosas así" y no se preocupan por corregir errores que están ahí si ven que las personas que ya están involucradas con el sistema en cuestión no se preocuparon lo suficiente para solucionar este tipo de problemas de cosas. Una mente totalmente penetrante en mi humilde opinión!

Me interesaría ver qué hacen otras personas "en el carbón".

aplausos,

Answer 1

Definitivamente corregiré los malos comentarios.

A veces es solo para eliminarlos para que no se extravíen.

Mejor aún, prefiero refactorizar el código para que los comentarios no sean necesarios - el código de auto documentación es mejor que los comentarios porque no se puede obsoleto.

Answer 2

Siempre tratan de actualizarlas si puedo, o por lo menos poner una nota en el sentido de que podrían estar equivocados. Es una inversión que vale la pena por una pequeña cantidad de tiempo.

La otra cosa que siempre hago es agregar cualquier número de error relevante, y qué efecto tuvieron esas ediciones, eso siempre es útil para ver más adelante.

Answer 3

Si el comentario es necesario, lo actualizaré; de lo contrario, intentaré cambiar el código hasta el punto en que pueda eliminar directamente el comentario y dejar que el código se documente.

Answer 4

Recientemente comencé a seguir más consejos de Uncle Bob's Clean Code y estoy tratando de transformar comentarios en funciones que encierran (extraen) el código comentado en una función que es al menos tan significativa como el comentario que reemplaza.

Answer 5

Corregiría los comentarios.

¿Por qué no solucionas cualquier problema que puedas? Si entiende el código en el que está trabajando, los comentarios deberían ser los más fáciles de solucionar. Obviamente, si te has tomado la molestia de profundizar en ello, el código debería quedar mejor de lo que lo encontraste.

Incluso diría que en los grupos donde varias personas tocarán el código, los comentarios podrían considerarse tan importantes como el código en sí. Sin él, la comunicación de ideas se rompe.

En la práctica, probablemente no hago el mismo comentario que debería. Es difícil admitir que usted u otra persona probablemente buscarán en su "obra maestra" más adelante.

Answer 6

Si su documentación se está generando a partir de los comentarios (lo recomiendo de todos modos), entonces sí, mantengo los comentarios meticulosamente sincronizados con el código.

Answer 7

Inmediatamente corrijo los comentarios si veo un problema, y ​​probablemente anoto qué se necesitaría para mejorar el código.

Si luego me golpea un autobús, el código es mucho mejor para mi atención rápida y puntiaguda.

Luego, si tengo tiempo, ordenaré el código por sí mismo (corregirlo generalmente requiere una prueba de regresión que consume mucho tiempo). Si no, lo dejaré para otro día, pero al menos sabré cuál es el problema de inmediato cuando tenga tiempo para volver a él.

Answer 8

Los comentarios a menudo son útiles para informar a los programadores o mantenedores futuros sobre lo que hace el código o por qué lo está haciendo de esa manera.

Si cambia el código sin actualizar los comentarios, en el mejor de los casos será confuso, si no francamente engañoso.

Answer 9

Me esfuerzo por seguir la Regla Boy Scout y dejar el código más limpio de lo que lo encontré. Buscaré actualizar el comentario o refactorizar el código para obviar la necesidad del comentario. Encuentro que, en general, es mejor no hacer ningún comentario que el de tener un comentario incorrecto.

Answer 10

Si el proyecto está bajo control de versiones (y debería serlo hoy en día, pero nunca se sabe) y hay una gran cantidad de comentarios desactualizados, elimino el trozo y dejo un nuevo comentario en el sentido de que He eliminado un montón de comentarios antiguos que ya no me parecían esclarecedores, y envío con una nota que eliminé los comentarios obsoletos.

Finalmente, quitaré el comentario que menciona la eliminación o lo reemplazaré con comentarios que se apliquen al nuevo código.

---

Sin embargo, aquí está el inconveniente de cambiar viejos comentarios, supuestamente sin sentido en un sistema que está siendo mantenido por un grupo de programadores:

Los comentarios no están actuando como comentarios más! Están actuando como hitos para los programadores familiarizados con el código. Son hito comentarios a diferencia de comentarios explicativos.

Los programadores en realidad pueden estar buscando palabras clave en comentarios de referencia para navegar por el archivo.

Si elimina los comentarios históricos, o incluso los modifica, puede ralentizar drásticamente los programadores que los utilizan para navegar por el archivo. Estás jugando con los mapas mentales de personas que tienen una larga relación con el código, y harás más daño que bien. El cerebro es una cosa graciosa. Puede ser mucho más fácil recordar una palabra o frase en un comentario funky que el nombre de un método.

Me parece que si los comentarios son terriblemente desactualizados con el código, debe saber por qué. Parece increíblemente presuntuoso suponer que a los otros programadores no les importa el código. Tal vez lo hagan, tal vez no lo hacen. Si tomas los archivos de un chico que se fue, y tienes una propiedad clara, ¡atrévete! Si eres el chico nuevo entre un montón de tipos que han estado trabajando en el código durante 20 años, y hay otra evidencia de que se preocupan por el código, tal vez te está faltando algo.

Esto es similar a la cuestión de reformatear - cambiar el espaciado, alterar el lugar donde van las llaves de apertura, etc. Y mucho depende de la propiedad.¿Vas a estar en un archivo 20 veces más que el hombre al lado tuyo? ¿O 1/20º tan a menudo? Si es el último, ¿realmente quieres desorientarlo?

Así que asegúrese de que no sea lo que está haciendo, o mañana puede escuchar a alguien gritando: "¿Dónde diablos está esa función?"

Answer 11

cuando encuentro los comentarios inútiles generada GhostDoc-, a veces simplemente borro:

Cuál es el propósito de estos comentarios?

/// <summary> 
/// Saves the form properties. 
/// </summary> 
/// <param name="form">The form.</param> 
/// <param name="propertyNames">The property names.</param> 
void SaveFormProperties(Form form, string[] propertyNames); 

Answer 12

No corrijo los malos comentarios. Solo los borro. (O sustitúyalos por un solo guión como comentario.) En general, las fechas límite están cerca, así que podría demorar un segundo para seleccionar, luego eliminar un comentario negativo, pero pasar 30 segundos o más para reescribirlo sería una pérdida de tiempo. . (Y un desperdicio de su concentración.) Una vez que transcurre el plazo, las cosas se vuelven más relajadas de nuevo, momento en el cual es hora de una revisión general del código para regresar algunos comentarios nuevos.

Pero, de nuevo, tendría que notar los malos comentarios primero. En la mayoría de los casos, estos viejos archivos de código a menudo se usan sin ser revisados ​​tan de cerca. Y a menudo ya han demostrado que funcionan, ¿por qué iba a mirar los comentarios?

Answer 13

Corregiría los comentarios. Vi algunas respuestas que decían que volverían a escribir el código si los comentarios no estaban actualizados. Me parece absurdo reescribir el código de trabajo solo porque los comentarios son malos. Ese tipo de comportamiento incluso puede hacer que te despidan si tu trabajo es lo suficientemente importante.

Answer 14

Como programador relativamente nuevo, realmente no trabajo mucho tanto en códigos anteriores como en los míos, pero trato de volver de vez en cuando para asegurarme de que mis propios comentarios son medianamente cercanos a la verdad. No tiene sentido dejar comentarios que no describan adecuadamente la función del código.

Dicho esto, si tiene prisa, no tiene sentido perder demasiado tiempo actualizando los comentarios. Agregar uno al efecto de "Esto no está actualizado" resuelve el problema de mantener la navegación sin dejar de ser ambiguo en cuanto a la precisión.

Answer 15

Siempre corrijo los comentarios, principalmente porque normalmente soy el que trabaja en un fragmento de código. Para mí, puede ser un TOC, pero me gusta el código en el que estoy trabajando para que se vea bien: buenos nombres de variables, formateo (no es un problema ahora con IDE modernos) y comentarios.

No creo que el código se pueda "refactorizar hasta el punto en que sea autodocumentado". Se puede refactorizar hasta el punto en que solo se necesiten comentarios para funciones, procedimientos, variables de miembro, clases, etc., ya que cada llamada de función solo tiene 1-5 líneas cada una. Procedente de un fondo Lisp, me gusta programar a través de la descomposición, mucho más simple, comprobable y más fácil de probar como correcto.