¿Hay alguna razón lógica para generar automáticamente la documentación del código? [cerrado]

  

[...] documenta todo, y casi siempre con los documentos generados automáticamente de GhostDoc. ¿Hace esto y hay razones racionales para no dejar el código sin documentar si no va a escribir la documentación usted mismo?

No. La documentación generada por GhostDoc es boilerplate (similar a cómo crear una nueva clase OO en un IDE crea el boileplate para una clase con un constructor o algo así). La parte útil de la documentación es lo que seguiría después de agregar el boilerplate.

Mientras tienes que documentar todo en tu lugar de trabajo, parece que tus colegas encontraron la manera perfecta de hacerlo: simplemente finge.

En un lenguaje estático, la documentación de estilo Javadoc no es para los autores, es para los consumidores. La autogeneración simplemente facilita que los autores mantengan la documentación para que otras personas la consuman.

Si está usando un lenguaje estático y no está escribiendo una biblioteca para el consumo de terceros, la autogeneración no le compra mucho y, en mi experiencia, rara vez se usa. Si utiliza un lenguaje de tipo dinámico, la documentación de estilo javadoc se usa a menudo para documentar los tipos, incluso para uso interno, pero la autogeneración no conoce los tipos, por lo que todo lo que le ahorra es evitar la copia manual de la placa de calderas.

De cualquier manera, no piense que la autogeneración produce un producto terminado. Considérelo como un producto para usted, por lo que cualquier cambio que realice manualmente es significativo.

  

¿Hay alguna razón lógica para generar automáticamente la documentación del código?

¿Desde qué perspectiva?

Si estuviera dirigiendo la compañía o el grupo de desarrollo, entonces no hay una buena razón. Estoy firmemente en el campo de "los comentarios deben explicar por qué ". Forzar a la gente a comentar clases / funciones / propiedades es peor que inútil, ya que se quedan desactualizados, engañan al lector, se usan como excusa para no hacer un código legible, y así sucesivamente. Estos comentarios desperdician tiempo al escribirlos, leer el código y los errores causados por ellos. Algunos argumentarán que los documentos de la API de estilo JavaDoc son una razón para hacer comentarios, pero incluso bajo ese argumento una pequeña parte de su código debe ser parte de la API pública, y JavaDoc no es un reemplazo de los documentos API reales.

Como desarrollador, he trabajado en algunos lugares que solicita comenta en estos lugares, a pesar de mi opinión. Como no tengo el tiempo ni la paciencia para escribir un montón de basura que nadie va a usar, en lugar de eso lo hago con GhostDoc. Esto me permite pasar ese tiempo haciendo cosas que importan. Mucho más eficiente que cambiar la política corporativa.

Otra cosa buena que he encontrado usando GhostDoc es que sirve para comprobar que mis nombres son buenos. Si GhostDoc no puede generar documentación decente para una función, es un olor que mi función o nombres de parámetros pueden ser malos. Si bien no usaría la herramienta para solo esto, es un pequeño efecto secundario si me hacen perder el tiempo de todos modos.

EDIT : entendí mal la pregunta original; aunque creo que generar documentación (es decir, sin código documentos ) puede ser extremadamente valioso (vea la respuesta original con respecto a Doxygen), generando automáticamente comentarios (que es algo que realmente hace GhostDoc) me parece una locura. No puedo entender por qué alguien esperaría que un programa pudiera leer el código fuente sin comentarios y escribir comentarios que realmente lo aclararán.

Es concebible para mí que una utilidad de generación de comentarios extremadamente "inteligente" pueda estar programada para reconocer ciertos patrones y generar comentarios de estilo "cómo"; por ejemplo, podría reconocer algoritmo de cálculo de varianza de Knuth y proporcionar un comentario que explique cómo funciona y por qué el algoritmo ingenuo no sería apropiado Tal vez una utilidad de este tipo podría incluso programarse para reconocer patrones de diseño orientados a objetos canónicos (por ejemplo, Abstract Factory) e insertar comentarios que indiquen qué patrón se está utilizando y qué clases están desempeñando qué roles.

Pero en mi opinión, los comentarios más útiles no explican "cómo" funciona algo, ya que el código mismo debería mostrar esto, pero " por qué " comenta, explicando "por qué" algo en particular se está haciendo. Como lo señaló David Hammen en los comentarios a continuación, para generar "por qué" comentarios, una utilidad debería "leer la mente del programador". Obviamente esto es imposible.

Sin embargo, en función de los ejemplos dados, parece que GhostDoc ni siquiera cumple la tarea de crear verdaderos comentarios de estilo "cómo". Por lo tanto, es, en mi opinión, peor que inútil, ya que lo que genera genera puede ser insano y engañoso (como en el segundo ejemplo).

Respuesta original: por qué la documentación automática extracción y formateo es una buena idea

Mi equipo de software utiliza Doxygen. La razón principal para esto es que necesitamos código no fuente (es decir, legible por no programadores) documentación de las características del código / comportamiento / etc, pero creemos que es una mejor práctica para integrar esto en el propio código fuente que para mantenerlo como un segundo documento . Esto nos ayuda a mantener la documentación sincronizada con el código fuente (aunque, por supuesto, eso nunca se puede garantizar completamente, y mucho menos automatiza) y minimiza la sobrecarga de la redacción de la documentación (ya que la documentación de un fragmento de código puede incorporarse de manera trivial en el archivo que contiene el código en sí).

Por lo tanto, el objetivo de nuestro uso de Doxygen no es extraer información del código en sí, sino mantener la documentación del código fuente lo más cerca posible del código fuente en sí.

Esto también nos permite usar una sola herramienta para crear tanto una "teoría de operaciones" que describe nuestra base de código completa como varios conjuntos de "notas de lanzamiento" que describen el producto de software pero que de hecho no contienen ninguna "documentación de código real" "en el sentido típico.

En cuanto a por qué necesitaríamos documentación sin código fuente del comportamiento de nuestro código, existen dos razones:

• Nuestro producto no es meramente software; es una herramienta compleja que integra muchos componentes de hardware, incluidos algunos láseres y fluidos sofisticados. Necesitamos ingenieros sin mucha experiencia en software para tener una buena comprensión de exactamente cómo se comportan los elementos internos de nuestro código, y decirles que "lea el código fuente" no se logrará esto.
• Debemos seguir un buen número de regulaciones de calidad, algunas mandadas internamente por la compañía y otras legalmente mandadas por el gobierno federal. Aunque el proceso de calidad es (o al menos puede ser) extremadamente valioso y útil, implica una cantidad no despreciable de gastos generales, parte del cual es deber del equipo de software proporcionar este tipo de documentación detallada del software. Una vez más, la integración de esta documentación con el propio código minimiza los gastos generales y nos ayuda a mantener la documentación actualizada.

Tenga en cuenta que el segundo punto es bastante similar al punto que otras respuestas han hecho acerca de los gerentes que desean la tranquilidad (o los derechos de fanfarronear) de saber que existe cierta documentación (independientemente de la calidad) para cada pieza del código fuente; esa forma de enmarcarlo, sin embargo, ignora el hecho de que la documentación exigida externamente puede tener algunas ventajas legítimas.

Ciertamente, la documentación automatizada es particularmente útil cuando puede reproducir descripciones perspicaces y apropiadas escritas por los autores del código. De lo contrario, es solo un formateador automático glorificado.

Pero el formato no es inútil. Hay valor en poder encontrar los métodos públicos de un componente más grande de una sola mirada, ordenados y garantizados para ser completos. Si necesita un mutador frobnick y no está allí, sabe no está allí sin pasar por el código fuente. (Los resultados negativos también tienen valor: sabes que tienes que hacer algo y tienes más tiempo para hacerlo porque no tenías que vadear).

Entonces, sí, la generación automática de documentos agrega algo . Ciertamente, no tanto como probablemente suponen los gerentes, y generalmente ni siquiera tanto como lo haría un buen editor de copia, pero no nada.

No sé sobre otros entornos, pero cuando se trata de proyectos PHP grandes (a menudo de código abierto), otras personas han escrito que phpXRef es un salvavidas absoluto (especialmente si el documento está en línea y Google puede indexarlo).

Incluso un proyecto mal comentado puede al menos ayudarme a rastrear dónde se han definido las cosas y dónde se usan (por ejemplo, al refactorizar).

Cuando están bien comentadas, las páginas resultantes forman una Biblia perfecta para el código base (para mi uso de todos modos).

Además, mi IDE preferido generará automáticamente el bloque de comentarios (si escribo / **) que hace aproximadamente el 75% del trabajo de comentarios para mí. Es sorprendente la cantidad de cosas estúpidas que me impidieron cometer durante mi vida como programador solo porque tuve que explicarle a otras personas (y a mí en el futuro) lo que estoy haciendo. Cuando mi comentario para el generador de documentos es más grande que el método, por lo general significa que no he tomado suficiente café y podría querer pensar un poco más.

Esos mismos bloques de comentarios también crean el texto de "ayuda" de finalización en línea para que pueda ver exactamente lo que esperaban los otros codificadores mientras escribo la llamada de función. Esto es un aumento masivo de la productividad para mí (especialmente en los casos poco frecuentes en los que algún otro desarrollador útil ha escrito "por bondad hacer / no hacer X" que puede ahorrar mucho dolor.

No puedo enfatizar lo suficiente lo útil que es tener los tipos de entrada esperados especificados en proyectos PHP complejos (ya menudo mal nombrados) y el orden de los argumentos en métodos usados con menos frecuencia. Incluso con mi propio código no siempre puedo recordar los argumentos que especifiqué para algo que no he tocado en una era.

En un caso, lo que significaba que la razón de los problemas recurrentes era que, por algún motivo, se refleja mal en desarrolladores anteriores. Algunas funciones e incluso constantes se definieron en una gran cantidad de lugares (con un grado de inconsistencia para agregar "diversión" ). Esa fue la señal para alejarse del proyecto.

Por lo tanto, las razones incluyen guardar a los desarrolladores posteriores una pila de tiempo, hacer un seguimiento de dónde se llaman (y definir) las funciones, detectar codificación tonta, encontrar (como ha señalado otro) cuando obviamente falta algo, simplificar la refactorización (nunca es divertido) ) y en muchos casos se hace una idea de lo que el desarrollador estaba tratando de hacer (asumiendo que dejó algunas notas).

Si el proyecto es lo suficientemente complejo como para tener varias licencias en marcha (no es divertido) puedo ver rápidamente qué licencias se aplican a cualquier sección. Es cierto que este es un bono adicional.

En los proyectos más grandes que comenzaron antes de unirme, puedo ver qué desarrollador (asumiendo que etiquetaron el archivo de la clase con un nombre y un correo electrónico) creó la clase y simplemente poder encontrar y hablar con el desarrollador correcto es sumamente útil. / p>

Listas de tareas automáticas: usar la etiqueta @todo (común en el tipo de proyectos en los que me encuentro trabajando) significa que la documentación puede realizar un seguimiento de las cosas que necesitan más trabajo (o funciones que se reconocen como faltantes). Una vez más, mi IDE realiza un seguimiento de esto y solo actúa como una buena guía en cuanto a lo que necesita mi atención primero.

Tampoco subestimes el valor de mantener felices a los jefes de cabello puntiagudo con solo tocar un botón.

Por último (y muy importante para mí) elimina la sobrecarga no trivial de escribir todo eso y luego tratar de mantenerlo actualizado cuando algunos (leen muchos) codificadores comprometen cambios y no hablan con los encargados de la documentación. .

En resumen, los "comentarios de documentación automática" son vitales para mis hábitos de codificación. Estoy seguro de que hay muchos que piensan que eso es malo, pero también estoy seguro de que hay algunas personas que saben exactamente lo que estoy diciendo. No sé cómo sobreviví antes de descubrir phpXRef (y mi IDE favorito).

En esta forma es peor que inútil, pero solo porque se basa únicamente en la firma pública (que, en el caso de Javadoc, es visible de todos modos para cualquiera que lea el documento de API).

Pero es posible escribir herramientas de documentación automatizadas que consideren el cuerpo del método también. Como prueba de concepto, escribí un pequeño complemento de Eclipse que agrega una lista de otros métodos llamados desde el método documentado al Javadoc. (No todas las llamadas, por supuesto, puede definir filtros, por paquete, por ejemplo).

Y, de hecho, lo encontré bastante útil al diseñar mentalmente una base de código completamente desconocida. Por supuesto, es un caso de uso muy limitado, pero definitivamente fue una ayuda.

Basándose en esa experiencia, la respuesta a la pregunta es: sí, pero necesitamos herramientas mucho más inteligentes.

Actualización: Por supuesto, una pregunta adicional (una que debe hacerse antes de escribir cualquier tipo de documentación) es quién es el público objetivo. Si estamos documentando una API pública para clientes de esa API, agregar todos estos detalles de implementación es un gran no-no, ya que cualquier cosa que coloque en el Javadoc es técnicamente parte de la API.

Pero si el público objetivo son otros desarrolladores que trabajan en el mismo producto, la adición automática de información sobre los detalles de la implementación, como los métodos que modifican o leen un determinado campo, es aceptable y bastante útil.

A menudo es bueno usar los generadores de documentación para crear comentarios o "comentarios" que luego son revisados por los desarrolladores reales. A menudo utilizo la función auto-JavaDoc de Eclipse para generar el comentario del encabezado con los tipos de parámetros y los valores de retorno ya completados, luego simplemente agrego la "carne" de la documentación.

Como desarrollador de C #, utilizo Stylecop, que ordena comentarios para todas las clases, métodos, etc. Autogeneré estos comentarios usando una herramienta. La mayoría de las veces, los comentarios generados por la herramienta son suficientes y podrían inferirse por el nombre del objeto, por ejemplo. una clase de persona tiene un campo de identificación.

Pero SI quiero comentar un método no obvio, es muy fácil expandir la documentación de repetición y algunas explicaciones sobre lo que hace. Como ejemplo: tengo un método en mi clase de persona, que devuelve Nombre + Apellido, pero agregué un poco de documentación sobre lo que está sucediendo cuando falta uno de los dos.

En resumen: creo que el docu de placa de caldera puede ser perjudicial si nunca cambia el texto proporcionado por el generador. En ese caso, es sólo el ruido de la línea. Pero si los ve como una plantilla, bajan la barra para proporcionar comentarios buenos y útiles para usted o sus consumidores. ¿Podrías escribir los comentarios sin autogenerarlos? Claro, pero tendría que cumplir con el formato (que en el caso de C # es bastante detallado y molesto de generar a mano) y eso reduce la posibilidad de que realmente proporcione este comentario en al ...

Evita la tautología

La única vez que necesite cualquier tipo de documentación para el código es explicar por qué un método / función está haciendo algo, el nombre debería ser suficiente para lo que está haciendo .

Si está haciendo algo que no es idiomático, o viola el principio de menos asombro luego se requiere documentación.

La documentación generada automáticamente que es solo un formateador para la salida de información es casi exigida por los consumidores de su código. Javadoc hace esto extremadamente bien.

No todo se debe documentar manualmente

Cosas como los métodos getXXX / setXXX deben explicarse por sí mismos, por lo que la documentación que se genera automáticamente y que le permite saber que existe es bien recibida.

La documentación del código, al menos del tipo "automático", representa el mínimo denominador común para las personas que intentan entender la aplicación.

Los usuarios más sofisticados no apreciarían la documentación de código automático. Preferirían mucho más tener una documentación "dirigida" que les diga qué (poco) necesitan que se les diga.

Los usuarios menos sofisticados no lo apreciarían por la razón opuesta; Ellos no lo entenderían de todos modos.

Los usuarios más "apreciados" de la documentación de códigos automáticos son aquellos para quienes "un poco de conocimiento" es algo peligroso. "Pueden o no entender la documentación (aunque es probable que lo hagan), pero se sentirán bien acerca de "mantenerse en el círculo". Esta audiencia incluye la mayoría de los tipos "gerenciales". Si esa es su audiencia principal, la documentación de código automático podría ser una buena cosa.

la respuesta simple a "por qué generar documentos" se puede responder simplemente mostrando MSDN.

Imagine que intenta escribir un programa que usa cualquier biblioteca donde no hay documentación de API. Sería una pesadilla. MSDN es un gran ejemplo del tipo de documento que se puede generar a partir del código fuente y los comentarios y constituye un recurso esencial para los desarrolladores.

Si está escribiendo una aplicación (es decir, no es una biblioteca para ser consumida por otros), entonces tal vez haya un motivo para no preocuparse, pero incluso entonces, la cantidad de una aplicación grande, solo interna, no contiene montón de bibliotecas de todos modos? Cuando te unes a un equipo así, será útil tener un documento de API que se pueda explorar.

Ninguna herramienta va a escribir su documentación por usted, pero sí le dan la placa de repetición que tendría que escribir manualmente de todos modos, algunas herramientas (como doxygen) también generarán diagramas y listas de referencias (de llamadas y llamadas). funciones, por ejemplo) que no se descubrirían fácilmente incluso al mirar el código fuente.

Obviamente, se debe aplicar el sentido común pragmático a lo que se documenta, las propiedades y funciones secundarias pueden ignorarse (y omitirse de generación incluso en las herramientas), pero en ningún momento nadie debe decir "ahí está el código fuente, eso es documentación suficiente" en cualquier momento.