¿Los comentarios obsoletos son un mito urbano?

Constantemente veo personas que afirman que "los comentarios tienden a quedar desactualizados". La cuestión es que creo que he visto quizás dos o tres comentarios desactualizados en toda mi carrera. La información desactualizada en documentos separados ocurre todo el tiempo, pero en mi experiencia los comentarios desactualizados en el código en sí son extremadamente raros.

¿Acabo de tener suerte con quién trabajo? ¿Son ciertas industrias más propensas a este problema que otras? ¿Tiene ejemplos específicos de comentarios desactualizados recientes que haya visto? ¿O los comentarios obsoletos son más un problema teórico que uno real?

Constantemente

Realmente no puedo creer que soy el único que nada en comentarios anticuados y engañosos. En el caso improbable, esto ayuda a comprender:

Probablemente depende más importante de la antigüedad del código. El siguiente factor sería la rotación del personal.

Hago trabajos de I + D y mantenimiento a partes iguales. El R&D es un código nuevo, generalmente cosas que están un poco fuera de lo común. Muchos de mis colegas creen en dar muchas explicaciones comentadas cuando intentan algo para lo que todavía no hay una biblioteca. Dado que la relación comentario a código es más alta de lo normal, solo hay más oportunidades para que las cosas no estén sincronizadas.

El código de mantenimiento ... Soy un mantenedor activo en un sistema que tiene más de 10 años y otro que tiene más de 5. El código y los comentarios de 10 años son atroces, como era de esperar. En 10 años, obtienes muchas manos en la base de código y ya nadie tiene idea de cómo funciona todo. El código y los comentarios de 5 años son bastante buenos porque la rotación del equipo ha sido bastante baja.

Trabajo en casi todos los servicios, incluso nuestros productos están altamente personalizados para un cliente en particular.

Ejemplos específicos:

• Comentarios que describen la mejora del rendimiento para una metodología particular, como evitar una copia en memoria. Un gran problema cuando una máquina de gama alta en un Pentium 2 con MB de RAM, pero ahora casi no es un problema.

• TODOS

• Bloques de código copiado, incluidos los comentarios. El comentario puede haber tenido sentido en su ubicación original, pero aquí apenas tiene sentido

• Bloques de comentarios sobre el código comentado (Quién sabe cuántos años lleva allí).

En todo esto, se ve una tendencia a no mantener los comentarios y el código al mismo nivel que el software. Los IDE y los hábitos básicos del desarrollador no ayudan con esto, mi ojo ha sido entrenado para superarlos. Creo que los comentarios obsoletos son relativamente baratos de evitar en proyectos activos y de campo verde. Si puede mantener alta la relación código / comentario, no es un gran problema mantenerlos actualizados. Es un poco más difícil justificar la búsqueda de estas cosas cuando tiene un presupuesto de x horas para una corrección de errores en un sistema de producción.

"Los comentarios tienden a quedar desactualizados".

He visto que esto sucede con la frecuencia suficiente para saber que esto puede ser un problema.

La cuestión es que creo que he visto quizás dos o tres comentarios desactualizados en toda mi carrera.

Creo que debería ser perfectamente posible trabajar en un entorno en el que todos cuiden suficientemente los comentarios y los mantengan. Es solo un pequeño esfuerzo adicional mirar los comentarios cerca del código que está editando y actualizarlos cuando sea apropiado. En caso de que los comentarios estén tan lejos que no los note de inmediato, de todos modos fueron malos comentarios, y no deberían haberse agregado en primer lugar (o al menos no están allí).

Además, generalmente junto con la afirmación de que los comentarios tienden a quedar desactualizados, sigue la afirmación de que esto reduce la legibilidad y confunde a las personas. Esto es algo que aún no he experimentado. Cada vez que encuentro un comentario desactualizado, veo claramente lo que cambió y solo actualizo el comentario en consecuencia para representar el código más nuevo, aunque con un esfuerzo adicional.

Un estudio reciente de Roehm et al. 2012 observa lo siguiente:

21 participantes [de 28] informaron que obtienen su información principal del código fuente y comentarios en línea, mientras que solo cuatro declararon que la documentación es su principal fuente de información.

Esto está en línea con su sospecha de que los comentarios en el código en sí mismo generalmente se consideran muy útiles. Esto indica que se debe trazar una línea clara entre la documentación desactualizada y los comentarios desactualizados .

_{Roehm, T., Tiarks, R., Koschke, R., y Maalej, W. (2012, junio). ¿Cómo comprenden los desarrolladores profesionales el software? En Actas de la Conferencia Internacional de 2012 sobre Ingeniería de Software (pp. 255-265). IEEE Press.}

Los comentarios obsoletos son un olor a trabajo. Es como tener pruebas unitarias desactualizadas o desatendidas: muestra que los buenos procesos que alguna vez estuvieron activos en la tienda están degenerando en codificación de vaqueros. La "cultura de ingeniería" adecuada de tomarse el tiempo para hacer las cosas correctamente se ha roto. Es probable que el proyecto / empresa se endeude técnicamente.

En resumen, sí, has tenido suerte. Si tienes una serie de tiendas razonablemente bien administradas hasta ahora en tu carrera, es muy posible que no veas tanto. Pero en las tiendas más típicas y menos manejadas, esto corre paralelo al resto del caos.

Los comentarios son como pruebas, son muy buenos cuando están actualizados, pero pueden dificultar aún más la comprensión del código si no los hay.

Si nunca has visto ningún comentario desactualizado, has tenido mucha suerte.

La mayoría de las bases de código con las que he trabajado han estado llenas de comentarios desactualizados, y por lo general ignoro los comentarios por completo, ya que generalmente son fuente de confusión en lugar de ayuda.

Los comentarios obsoletos a menudo aparecen en JavaDoc:

• Listado de argumentos que ya no existen
• No explica todos los argumentos (los que faltan probablemente se agregaron más tarde)
• Cosas similares para excepciones, etc.

Además, a veces los comentarios indican cosas como "haga esto aquí por rendimiento" cuando la mayoría de las consideraciones de rendimiento tienden a quedarse obsoletas incluso más rápido que el código en sí.

Trato con comentarios desactualizados de vez en cuando. Ciertamente no es un mito urbano. La gente lo menciona en las listas de las peores prácticas, no porque te golpee muy a menudo, sino porque cuando lo hace, generalmente te cuesta mucho tiempo y esfuerzo.

En nuestra base de código, la mayoría de los comentarios desactualizados son causados ​​por el uso del patrón (anti) de describir el comportamiento del método cerca de su llamada y no cerca de la declaración del método. Ocurre cuando alguien extrae un fragmento de código largo en un método que solo se llama una vez en ese momento y luego comenta la llamada al método. Entonces terminas con algo como esto:

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

Y el método se declara en algún lugar a continuación sin comentarios. La gente se mete con estos métodos a lo largo de los años tratando con cambios de especificaciones y arreglando errores, y eventualmente terminas con un método que no ordena la lista y lanza una excepción cuando encuentra la característica vacía. Por lo tanto, el comentario anterior es un comentario desactualizado que eventualmente le costará algún tiempo en el depurador. Esto sucede en algunas bases de código.

Pregúntate esto. ¿Alguna vez ha cambiado una línea de código y no ha cambiado los comentarios asociados o agregado otros nuevos?

He trabajado con mucho código heredado y los comentarios a veces ni siquiera son relevantes.

En su mayor parte, mi experiencia coincide con la suya, pero me he encontrado con un caso en el que eso era cierto en toda la base de código. Era una aplicación que había sido escrita años antes por una tienda de consultoría que ya no estaba "en buenos términos" con el cliente.

La compañía hizo un trabajo excepcional al comentar el código, pero los programadores que lo mantuvieron desde la transferencia original fueron parte de la mentalidad de "solo cambiar lo que absolutamente hay que cambiar", lo que en sí mismo no es malo. Desafortunadamente, mantuvieron esa misma actitud hacia los comentarios también, lo que condujo a una desconexión bastante grande entre los comentarios y el código con el tiempo.

No veo demasiados comentarios descriptivos desactualizados, pero sí veo muchos comentarios TODO que han estado allí durante años. Desearía que fueran como cápsulas del tiempo y dije algo como esto:

//TODO: In 15 years AND NO SOONER... actually implement this method.

Los últimos 3 proyectos en los que trabajé pasé varios días eliminando comentarios obsoletos, engañosos y simplemente inútiles de la base de código. Siempre que sea posible y necesario, los reemplazo con comentarios más apropiados, pero la mayoría de las veces es solo una cuestión de eliminar el comentario y seguir adelante.

He hecho lo mismo en casi todas las bases de código que he tomado de otros, generalmente después de que no se mantuvo durante un tiempo y los propietarios originales se fueron y / o no quisieron o no pudieron realizar la transferencia adecuada.

Podría ser la disminución en el uso de comentarios. ¿Cuánto del código de alguien califica? Por un lado, alguien realmente tiene que incluir comentarios para que estén desactualizados. En segundo lugar, el código que se comentó tiene que cambiarse. No estoy seguro de que un alto porcentaje de código califique.

Solo tiene que confiar en un mal comentario para arruinar una gran parte de una aplicación y perder mucho tiempo.

En una organización que produce mucho código, es difícil mantener los comentarios sincronizados. La mejor manera de entender lo que está sucediendo es mediante el uso de softwares que dibujan el diagrama de flujo de control del módulo en el que está trabajando. Esa es la única forma de tener una idea de lo que hace el software.