Estudios sobre ganancias / pérdidas de productividad de la documentación del código

Después de mucho buscar, no he podido responder una pregunta básica relacionada con un supuesto conocido en el mundo del desarrollo de software:

LO QUE SE SABE:

La aplicación de una política estricta sobre la documentación adecuada del código (ya sea etiquetas Doxygen, Javadoc o simplemente una gran cantidad de comentarios) agrega gastos al tiempo necesario para desarrollar el código.

PERO:

Tener una documentación exhaustiva (o incluso una API) trae consigo ganancias de productividad (se supone) en los desarrolladores nuevos y experimentados cuando agregan funciones o corrigen errores en el futuro.

LA PREGUNTA:

¿Se requiere el tiempo de desarrollo adicional para garantizar que dicha documentación sea compensada por las ganancias en productividad en el futuro (en un sentido estrictamente económico)?

Estoy buscando estudios de casos o respuestas que puedan traer evidencia objetiva que respalde las conclusiones que se extraen.

¡Gracias por adelantado!

El artículo "El estilo tipográfico es más que cosmético" es bastante antiguo pero es muy interesante: http://portal.acm.org/citation.cfm?id=78611 .

Al ser viejo, no incluye todas las cosas elegantes que serían posibles en estos días, pero muestra claramente que la documentación del código sí importa.

Para aquellos que, como yo, no tienen acceso a la biblioteca digital ACM, crearon dos grupos de programadores y les dieron el mismo código para estudiar. El grupo A recibió solo el código con los comentarios habituales, el grupo B recibió una lista bastante impresa con una tabla de contenido, referencias cruzadas y todas las sutilezas posibles en 1990.

Luego les pidieron a los dos grupos que realizaran ciertas tareas en el código (por ejemplo, extender una función, encontrar un error, ...) y los calificaron en términos de velocidad y calidad de las respuestas.

Para equilibrar el grupo tenían el mismo número de programadores expertos y junior.

Bueno, resultó que el grupo B (el que tiene una lista bastante impresa) obtuvo un puntaje mejor que el grupo A en numerosas pruebas. Y, en casos específicos, solo los más expertos del grupo A lograron superar al programador junior del grupo B.

El artículo dice más, pero esto es lo que puedo recordar de memoria (todavía debería tener el artículo impreso en alguna parte).

Al menos para mí, parece obvio que el código legible vale mucho más que la documentación que solo sirve para compensar el código mal escrito. Tiendo a considerar los comentarios en el código como un desafío para ver si puedo eliminar el comentario reescribiendo el código y hacerlo más autoexplicativo.

No puedo respaldar eso con ninguna evidencia contundente, excepto bueno, sentido común.

No tengo ningún estudio para citar, pero sí tengo una regla simple: si vuelvo a mi código dos semanas después y no puedo entender de inmediato lo que hice, o necesita más comentarios o debe simplificarse .

Ciertamente, el código mismo debe documentar cómo funciona su código. Pero el tiempo dedicado a escribir comentarios que explican cuidadosa y sucintamente por qué su código está escrito de la manera en que seguramente se amortiza a largo plazo, incluso si usted es la única persona que mantiene el código.

La vida útil de una pieza de software se gastará principalmente en la etapa de mantenimiento, por lo que cualquier cosa que ayude al programador a seguirle para comprender lo que está sucediendo seguramente proporcionará retornos financieros, porque ayuda a que el desarrollador se acelere más rápido.

En cualquier API que no sea trivial, documentar la API en el código es casi inútil. Esto se debe a que el poder en la API proviene de cómo funciona en conjunto como una unidad completa (no de cómo funcionan los métodos / objetos individuales).

Por lo tanto, más útil que la documentación verdadera es un documento similar a un libro de cocina que explica los patrones de uso esperados de la API y ejemplos de cómo resolver algunas situaciones obvias (que utilizan la mayoría (no el 100%) de la API).

La decisión de si un método dado es, sin herramientas que probablemente aún no se hayan inventado, demasiado subjetivo para requerir que se escriba la documentación.

Cualquier práctica de adivinanzas, como "todos los métodos públicos" o todas las clases en un paquete dado, etc., puede ayudar pero es demasiado difícil de recomendar más allá de los casos de uso específicos.

Mi sugerencia: enseñe a sus desarrolladores buenas prácticas, cómo identificar los métodos que son importantes para documentar (API formal o informal, de uso común, métodos de código auxiliar, complejos o esotéricos) y dejarlos gobernarse a sí mismos.

(Muy relacionado: ¿puede haber demasiada uniformidad en los estándares de codificación? )

^{Pido disculpas por no tener ningún estudio que citar, pero sospecho que este es un problema en el que cualquier intento de medirlo afectaría demasiado el resultado como para sacar conclusiones generales.}

Creo que necesitamos separar el código "regular" de las API públicas a este respecto. Para el código regular, he llegado a estar totalmente de acuerdo con que la mayoría de los otros respondedores en ese código deben auto documentarse y leerse casi como una prosa . Si mi código no es así, generalmente es mi culpa, por lo que en lugar de documentarlo, debería ser refactorizado. Los métodos pequeños que hacen una sola cosa a la vez, trabajar en un solo nivel de abstracción, tener un nombre correcto y descriptivo , pueden ser de gran ayuda para lograrlo.

El problema con los comentarios es que se pudren. Tan pronto como agrega un comentario, comienza a vivir una vida independiente del código que acompaña. ¿Cuán grande es la posibilidad de que el próximo desarrollador que modifique el código actualice debidamente los comentarios relacionados también? En mi experiencia, cerca de cero. El resultado final después de algunas modificaciones es que el comentario desconcierta o engaña a las personas en lugar de ayudarlas.

Las posibles excepciones son el código de rendimiento optimizado o el uso de un algoritmo específico . En este caso, es útil agregar comentarios para describir por qué el código se ve así, una referencia al algoritmo, etc.

El trabajo fundamental sobre este tema es Clean Code .

OTOH, una API pública también debería estar bien documentada en Javadoc . Dado que puede ser utilizado por innumerables extraños totales con habilidades y suposiciones muy variadas, uno tiene que tomar precauciones para que sea lo más simple e inequívoco posible. Eso sigue siendo en gran medida una cuestión de diseño adecuado de API, pero también hay un papel importante para la documentación.

El problema es si ahorra tiempo al documentar su código frente a cada desarrollador posterior que tiene que tratar de averiguar qué hace. Si su código vuela a través de la revisión de código sin que nadie haga preguntas sobre lo que hace, probablemente esté en buena forma. No es demasiado difícil describir las suposiciones que haces sobre las entradas. Digamos que su método toma un objeto entero y devuelve un objeto de cadena. ¿Puede el int ser nulo? ¿Hay un valor mínimo / máximo (además de entero.MinValue / MaxValue)? ¿Puede devolver una cadena vacía o nula? ¿Lanza alguna excepción? Por supuesto, cualquiera puede encontrarlos mediante inspección, pero si suficientes otros desarrolladores van a usar su código, vale la pena ahorrar cada uno de unos minutos. Además, les da a los probadores una ventaja en la creación de pruebas para confirmar su código.

Este es ciertamente un tema interesante, ya que siempre ha habido argumentos sobre si el desarrollador debe pasar tiempo creando o manteniendo documentos o no, pero el hecho es que el código debe estar bien escrito y muy bien comentado, de esta manera cuando el desarrollador vuelve a visitar el código de lo que él o ella no tiene que perder tiempo reflexionando sobre cómo se escribió el código y qué se suponía que debía hacer en primer lugar, además, si un nuevo miembro del equipo se une al equipo, también puede comprender la funcionalidad y el funcionamiento del código, ya que se ha documentado claramente.

Por lo tanto, el código debe estar muy bien comentado y debe ser un código auto documentado que no requiera ninguna documentación externa.

En mi carrera, he visto código con diferentes niveles de documentación y calidad (tenga en cuenta que la documentación y la calidad son preocupaciones ortoganales). Prefiero utilizar el tiempo dedicado a la documentación para mejorar la calidad. Para el caso simple, hay herramientas como GhostDoc que pueden ver una función y generar comentarios de documentos para usted. Si GhostDoc puede generar un comentario significativo que dice lo que hace su función, entonces obviamente ha logrado el objetivo de tener funciones bien nombradas.

En muchos casos, GhostDoc ni siquiera puede comenzar a decirle qué hace realmente una función. Es mejor dedicar su tiempo a resolver ese problema y (tal vez) usar ghostdoc para generar automáticamente su código.

Vea Clean Code y PPP de Bob Martin para una discusión más profunda.