Documentar lógica matemática en código

A veces, aunque no con frecuencia, tengo que incluir la lógica matemática en mi código. Los conceptos utilizados son en su mayoría muy simples, pero el código resultante no lo es: muchas variables con un propósito poco claro y algunas operaciones con una intención no tan obvia. No quiero decir que el código sea ilegible o no se pueda mantener , solo que es mucho más difícil de entender que el problema matemático real. Intento comentar las partes que son más difíciles de entender, pero existe el mismo problema que al codificarlas: el texto no tiene el poder expresivo de las matemáticas .

Estoy buscando una forma más eficiente y fácil de entender de explicar la lógica detrás de algunos de los códigos complejos, preferiblemente en el propio código. He considerado TeX: escribir la documentación y generarla por separado del código. Pero luego tendría que aprender TeX, y la documentación no estará en el código mismo. Otra cosa en la que pensé fue tomar una fotografía de las anotaciones matemáticas, ecuaciones y diagramas escritos en papel / pizarra, e incluirlos en javadoc.

¿Hay una manera más simple y clara?

PD Dar nombres descriptivos (en timeOfFirstEventlugar de t1) a las variables en realidad hace que el código sea más detallado y aún más difícil de leer.

Lo correcto en tales circunstancias es implementar el algoritmo, la fórmula o lo que sea con exactamente los mismos nombres de variables que en la fuente principal del mundo real (en la medida en que el lenguaje de programación lo permita), y tener un breve comentario encima diciendo algo así como "cálculo de distancia de Levenshtein como se describe en [Knuth1968]", donde la cita se vincula a una descripción fácilmente accesible de las matemáticas.

(Si no tiene esa referencia, pero su matemática es sólida y útil, tal vez debería considerar publicarla usted mismo. Simplemente diga).

Cuando tuve que implementar algoritmos como ese, hay un par de cosas que hago.

1. En la medida de lo posible, aísle el algoritmo a su propio método o preferiblemente clase. Mi proyecto actual tiene su propia Mathclase equivalente para agregar algoritmos complejos.

2. Proporcione un resumen de lo que se supone que debe hacer el algoritmo en términos generales, incluidas las siglas comunes o referencias abreviadas del término. Hago esto en el método mismo, por lo que vive con el código.

3. Proporcione un resumen del algoritmo en términos técnicos / matemáticos e incluya cualquier referencia externa que conozca. Nuevamente, hago esto con el método en sí mismo para que tenga una mejor oportunidad de mantenerse relevante. El texto sin formato no es excelente en este caso, por lo que citaré el término matemático lo mejor que pueda y aclararé en un comentario entre paréntesis. Por ejemplo, x^y (x raised to the power y)

4. Documente cómo estoy separando el algoritmo en componentes e indique qué representa cada variable en el algoritmo. p.ej.t1 is time of first event

5. Codifique el algoritmo y comente las partes complejas. Esencialmente, agregaré un comentario en cualquier lugar donde dé un paso que no sea obvio o directo dentro del algoritmo mismo. Especialmente me aseguro de comentar cualquier atajo no obvio y por qué están bien que pueda tomar dentro de la implementación.

6. Escriba algunas pruebas unitarias que validen la operación del algoritmo.

Finalmente, si es muy, muy, muy complejo, me resigno al hecho de que poseo ese código por el resto de mi tiempo en ese proyecto.

No me gusta confiar en un documento externo para que otra persona entienda el código. Sí, a veces puede ser necesario, especialmente al entrar en detalles arcanos. Pero siempre que es posible, trato de mantener todo dentro del código en sí para que tenga la oportunidad de mantenerse actualizado y fácilmente ubicado. En este caso, valoro la accesibilidad a la información sobre la expresividad de la documentación.

En nuestros proyectos, que giran en torno a la investigación en economía financiera cuantitativa, utilizamos MUCHAS matemáticas y seguimos una combinación de lo que ya se ha publicado:

1. Proporcione un enlace a la fuente principal que está utilizando. Para nosotros, la forma más fácil de hacerlo es usar el controlador BibTex, que es básicamente una identificación para un documento que puede ser buscado por todos los involucrados. Dependiendo de la fuente específica, también agregamos regularmente la referencia de ecuación.

2. Proporcione explicaciones para todas las variables. Nuevamente, usamos Tex para eso si el documento original usa letras griegas u otras. La razón de esto es que a menudo suficientes documentos y libros usan anotaciones diferentes. Si alguien necesita reelaborar las matemáticas, esto lo hace mucho más fácil.

3. Intenta codificar la ecuación en una sola pieza. Es mucho más fácil reconocerlo de esa manera. NO publique el código Tex de la ecuación completa en el código; o bien la ecuación es muy corta, y publicar tex es desordenado y superfluo, o la ecuación es enorme, y el código tex es inútil, a menos que lo compile (use un referencia en su lugar). Desmontar una ecuación en pedazos pequeños hace que sea realmente difícil entender qué está pasando (si al menos eres bueno en matemáticas).

En mi humilde opinión, la realización más importante es que las fórmulas a menudo dependen del contexto. Todos los trabajos de matemáticas que conozco se toman su tiempo para configurar el entorno del modelo; Deberías hacer lo mismo.

el texto no tiene el poder expresivo de las matemáticas

Tienes razón. Como ya está buscando una manera de hacerlo fuera del código, y Tex es una exageración además de tener una curva de aprendizaje empinada, mi recomendación es la siguiente:

Use OpenOffice.org/LibreOffice Editor de ecuaciones matemáticas.

Es gratis. Está abierto.

Puede usarlo visualmente o puede escribir las ecuaciones en un idioma especial.

No tiene que aprender el idioma de inmediato porque cuando usa la GUI, el "código" se genera en un panel para que lo vea.

En el panel superior puedes "dibujar" las ecuaciones usando una paleta. En el panel inferior se genera la notación equivalente. Puede hacerlo al revés una vez que tenga una idea de la notación, escriba la notación en el panel inferior y vea la salida gráfica en el panel superior.