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

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?

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.

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.

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").

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í.

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.