¿Dónde debería un programador explicar la lógica extendida detrás del código?

8

He desarrollado algunas bibliotecas cuantitativas en C # donde es importante comprender no solo la información clásica que acompaña a los comentarios XMLDoc (que contiene información básica con la firma del método) sino también las fórmulas matemáticas que se utilizan dentro de los métodos.

Por lo tanto, me gustaría poder incluir documentación extendida con el código, que podría contener, por ejemplo, fórmulas de látex, gráficos, etc.

¿Crees que dicha información debería incluirse en la documentación de la API?

¿O debería incluirse en un blog de desarrollo para obtener ejemplos?

¿Existen herramientas comunes que generalmente se usan para este tipo de propósitos?

SRKX
fuente
La lógica extendida, ¿puede entenderse en partes pequeñas, método por método, o el usuario debe leer la explicación completa antes de sumergirse en la API?
FrustratedWithFormsDesigner
En realidad, ambos. A veces me gustaría explicarle al usuario cómo debería usar algunas clases juntos, tal vez proporcionando un diagrama de clase y algunos ejemplos globales. También debe estar en algún lugar donde un programador principiante pueda mirar, por ejemplo.
SRKX
Los blogs son buenos para las conversaciones y pésimos para la documentación. Desea absolutamente que la versión del código y la versión del documento estén bien sincronizadas, y una publicación de blog tiene un ciclo de vida independiente del del código.
Ross Patterson

Respuestas:

14

En lo que a mí respecta, cuanto más cerca guarde la documentación del código, es más probable que se mantenga actualizado y más útil sea.

Es por eso que trato de mantener toda la documentación en el mismo repositorio que el código, incluso los manuales de usuario, y trato de mantenerla en un formato de texto sin formato que pueda ser fácilmente administrado por un sistema de control de revisiones.

Documentación en código

Parece que ya lo tiene cubierto, pero es importante recordar que el uso de las funciones de documentación en el entorno de desarrollo elegido ( pydoc para python, javadoc en java o comentarios xml en C #) es la técnica de documentación más importante. Facilitan la escritura de la documentación al mismo tiempo que escriben el código.

Si confía en volver y documentar las cosas más tarde, es posible que no lo haga, pero si lo hace mientras escribe el código, entonces lo que necesita documentarse estará fresco en su mente. C # incluso tiene la opción de emitir una advertencia de compilación si la documentación XML está incompleta o es inconsistente con el código real.

Pruebas como documentación

Otro aspecto importante es tener una buena integración y pruebas unitarias.

A menudo, la documentación se concentra en lo que las clases y los métodos hacen de forma aislada, omitiendo cómo se usan juntos para resolver su problema. Las pruebas a menudo los ponen en contexto al mostrar cómo interactúan entre sí.

Del mismo modo, las pruebas unitarias a menudo señalan dependencias externas explícitamente a través de las cuales las cosas deben ser simuladas .

También encuentro que usando el desarrollo basado en pruebas escribo un software que es más fácil de usar, porque lo estoy usando desde el principio. Con un buen marco de prueba, hacer que el código sea más fácil de probar y que sea fácil de usar a menudo es lo mismo.

Documentación de nivel superior

Finalmente, hay qué hacer con respecto a la documentación de nivel de sistema, arquitectura, desarrollador y posiblemente también del usuario final. Muchos abogarían por escribir dicha documentación en una wiki o usar Word u otro procesador de textos, pero para mí el mejor lugar para dicha documentación también es junto al código, en un formato de texto sin formato que sea amigable con el sistema de control de versiones.

Al igual que con la documentación en código, si almacena su documentación de nivel superior en su repositorio de código, es más probable que la mantenga actualizada. También obtiene el beneficio de que cuando extrae la versión XY del código, también obtiene la versión XY de la documentación. Además, si utiliza un formato compatible con VCS, significa que es fácil bifurcar, diferenciar y fusionar, al igual que su código.

Me gusta bastante primera , ya que es fácil de producir las dos páginas en HTML y documentos PDF a partir de ella, y es mucho más amigable que LaTeX , sin embargo, todavía puede incluir expresiones matemáticas de LaTeX cuando los necesite.

Cuando escribo código altamente matemático, también me parece útil tener algunos documentos wxmaxima en el repositorio de mi proyecto. Al ser texto sin formato, estos también se ramifican, difieren y fusionan muy bien, pero el uso de un sistema de álgebra computacional puede ayudarlo a verificar la coherencia de sus fórmulas y a documentarlas.

Mark Booth
fuente
8

Puede incluir dicha documentación dentro de los comentarios XML y generar manuales de LaTeX, páginas web y otros documentos a partir de ella utilizando doxygen . Use los elementos <remarks>y <example>para la prosa extendida.

Robert Harvey
fuente
3

Usaría documentación externa si necesita incluir diagramas de clase, gráficos, fórmulas, imágenes, etc. para explicar cómo funcionan sus bibliotecas. Incluya esta documentación externa como parte de los lanzamientos de su biblioteca en el formato que considere apropiado (LaTeX u otro). Si lo desea, puede consultar este documento desde su código (por ejemplo, "Consulte la documentación" Léame "para obtener más información").

Bernardo
fuente
2
... o hipervínculos directos a las partes relevantes, si es posible.
FrustratedWithFormsDesigner
0

La clave, creo, es la consistencia . Si ha anotado constantemente los métodos con comentarios que pueden extraerse, por ejemplo, por Doxygen, también tiene sentido incluir la descripción lógica extendida allí, ya que es allí donde es más probable que busquen otros desarrolladores. De repente, señalar al desarrollador a otro documento parece innecesario y solo confundirá a los desarrolladores.

Sin embargo, si la descripción de todo el programa se da en otra parte, entonces debe seguir con eso y dar la descripción lógica extendida allí.

gablin
fuente
0

Si cree que es necesario documentar las entrañas de un método en su API, entonces probablemente no haya definido / modularizado muy bien la interfaz.

Una API bien escrita no debe REQUERIR al programador que comprenda cómo funcionan las partes internas. Además, al documentar innecesariamente la forma en que funciona, está rompiendo la capa de abstracción y encerrándose en una implementación específica, lo que tampoco es bueno.

JohnFx
fuente
44
Estoy en completo desacuerdo. Para una API cuantitativa, el usuario necesita saber cuál es el algoritmo subyacente para saber si los métodos se adaptan a sus necesidades o para poder comprender el resultado (piense en la optimización, aproximaciones numéricas, etc.).
SRKX
Si eso es necesario, te sugiero que necesites liberar una biblioteca, una solución de código abierto en lugar de una API.
JohnFx