¿Existen estudios empíricos sobre los efectos de comentar el código fuente en la calidad del software, la capacidad de mantenimiento y la productividad del desarrollador? [cerrado]

11

Soy un defensor de comentar sobre el código fuente y documentar productos de software. Es mi experiencia personal y observación que trabajar en el código fuente que se comenta rigurosamente me ha ayudado de diferentes maneras cuando tuve que hacer crecer el software o mantenerlo.

Sin embargo, hay otro campo que dice que los comentarios no tienen ningún valor o que su valor es cuestionable. Numerosos defensores de la codificación sin comentarios sostienen que:

  • Si un fragmento de código está bien escrito, se explica por sí mismo y, por lo tanto, no necesita comentarios.
  • Si un código no se explica por sí mismo, refactorícelo y hágalo explicarse por sí mismo para que no necesite ningún comentario.
  • Su conjunto de pruebas es su documentación en vivo
  • Con el tiempo, el código y los comentarios se desincronizan y se convierte en otra fuente de dolores de cabeza
  • Agile dice que el código de trabajo es más importante que las pilas de documentación, por lo que podemos ignorar la escritura de comentarios

Para mí esto es solo un dogma. Nuevamente, mi observación personal ha sido que el software escrito por equipos de desarrolladores inteligentes y experimentados finalmente termina con una cantidad considerable de código que no se explica por sí mismo.

Nuevamente, la API de Java, la API de Cocoa, la API de Android, etc. muestran que si desea escribir y mantener documentación de calidad, es posible.

Habiendo dicho todo esto, las conversaciones sobre los pros y los contras de la documentación y los comentarios sobre el código fuente que se basan en creencias personales generalmente no terminan bien y no conducen a conclusiones satisfactorias.

Como tal, estoy buscando trabajos académicos y estudios empíricos sobre los efectos de la documentación del software, especialmente comentando el código fuente, sobre su calidad y capacidad de mantenimiento, así como sus efectos sobre la productividad del equipo.

¿Te has topado con tales artículos y cuál ha sido el resultado de ellos, si los hay?

productivity documentation code-quality maintainability engineering Behrang Saeedzadeh
fuente
2
Creo que esta es una pregunta interesante de todos modos, pero no me sorprende mucho que pueda cerrarse aquí. Es por eso que también publiqué esto en Quora.
Behrang Saeedzadeh
44
@gnat - Me parece que "¿Qué investigación se ha realizado en este aspecto del campo del desarrollo de software?" es una pregunta bastante diferente a las solicitudes de "por favor dame libros sobre un tema" que no son del todo bienvenidas.
Josh Kelley
1
Solo por leer el título: No hay estudios empíricos sobre los efectos de nada en la calidad. Si lo hubiera, este sitio no existiría.
Eufórico
2
@Eufórico sus dos declaraciones se contradicen entre sí. Si ignoramos el documento "loco" de 30 años, no hay conflicto. Pero de todos modos, no debemos ignorar los hallazgos solo porque son viejos, sino valorar críticamente cómo se relacionan con el trabajo moderno (como deberíamos con los nuevos resultados también).
3
@Euphoric Desearía que publicaras eso como respuesta, para poder desestimar tu falta total de investigación en tu afirmación general. Hay toneladas de documentos e investigaciones, empíricas y de otro tipo, sobre los efectos de diferentes técnicas en la calidad del software. ¿Has estudiado algo sobre ingeniería de software?
Andres F.

Respuestas:

9

En "El efecto de la modularización y los comentarios sobre la comprensión del programa" (1981), Woodfield, Dunsmore y Shen descubrieron que "los sujetos cuyos programas contenían comentarios podían responder más preguntas que aquellos sin comentarios".

Sin embargo, en "Aprendizaje de una métrica para la legibilidad del código" (2010), Raymond PL Buse y Westley Weimer descubrieron que los comentarios solo tienen un efecto limitado sobre la legibilidad y la calidad:

Del resumen:

Construimos una medida de legibilidad automatizada y ... demostramos que esta métrica se correlaciona fuertemente con tres medidas de calidad del software: cambios de código, informes automáticos de defectos y mensajes de registro de defectos ... Nuestros datos sugieren que los comentarios, en sí mismos, son menos importantes que simples líneas en blanco a los juicios locales de legibilidad.

De la página 12:

Descubrimos que los comentarios solo están moderadamente correlacionados con la noción de legibilidad de nuestros anotadores (33% de potencia relativa). Una conclusión puede ser que, si bien los comentarios pueden mejorar la legibilidad, generalmente se usan en segmentos de código que comenzaron menos legibles: el comentario y el código ilegible se equilibran efectivamente. El efecto neto parece ser que los comentarios no siempre son, en sí mismos, indicativos de alta o baja legibilidad.

Tenga en cuenta que los proponentes de "codificar sin comentar" no dicen que el código sin comentarios es mejor que el código con comentarios. Argumentan que un estilo particular de código sin comentarios, uno que extraiga código en métodos con nombres autodescriptivos, uno que introduzca variables explicativas , uno que tenga un buen conjunto de pruebas, es mejor que el código que no hace esas cosas pero tiene comentarios Esto podría complicar la aplicabilidad de cualquier estudio que se haya realizado.

Josh Kelley
fuente
1
El artículo de Woodfield et al trata sobre una variedad particular de comentarios, aproximadamente equivalente a lo que ahora se llamaría Javadoc: "Específicamente, esta investigación intenta determinar si los comentarios cortos, insertados justo antes de un módulo lógico, pueden ayudar a la comprensión al describir brevemente la función del módulo lógico y ayudando a definir los límites del módulo lógico ".
Debería haber agregado en ese momento: eso no quiere decir que no tenga valor, de hecho es un estudio interesante y bien construido. Solo pensé que era necesario decir que no están tomando en cuenta todos los comentarios.