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?