¿Cómo documento necesariamente estructuras de código necesariamente complejas?

Si tengo un código que es matemáticamente o estructuralmente bastante complejo e irreductible, ¿cómo haría para documentar este código? En particular, ¿cómo puedo asegurarme de que alguien que no tenga las habilidades matemáticas o arquitectónicas que yo pueda entenderlo de la documentación? ¿Debo documentar todas las matemáticas también? Enlace a un tutorial? ¿Alguna ayuda visual en el caso de estructuras complejas?

Esto realmente depende de lo complicado que sea el código y las matemáticas. El código en sí debería, como siempre, ser tan autodocumentable como sea posible. Nombre las variables correctamente, implemente métodos lógicos y concisos (en lugar de megafunciones), agregue documentación en línea cuando sea apropiado (es decir, cuando no es obvio lo que el código está haciendo realmente).

Si está utilizando un algoritmo no obvio, agregue un enlace a una referencia de la fuente. Esta es una práctica razonable porque le brinda al desarrollador una forma muy rápida de descubrir lo que está haciendo. Como dije, esto es útil si es un algoritmo no obvio pero complejo. Esto debería probar que (a) está haciendo algo que tiene sentido, y (b) alguien ha demostrado que funciona.

Un buen ejemplo es el trabajo que hice sobre la coincidencia de texto difuso. Hice una investigación sustancial en algoritmos e implementé lo que se conoce como 'algoritmo Smith-Waterman' (que en realidad se usa para secuencias de ADN, pero se aplica al 'emparejamiento' en general). Entonces, en lugar de simplemente implementar el algoritmo, encontré referencias en línea e incluí un enlace o dos. Como se indicó anteriormente, esto demuestra que (a) mi algoritmo coincide con el algoritmo publicado, y (b) el algoritmo ha sido revisado y demostrado que funciona.

Sin embargo, esto no necesariamente explica cómo funciona el código y qué se supone que deben hacer las diferentes clases. Cuando vaya a escribir documentación 'real', una guía para desarrolladores del sistema, debe explicar lo que ha hecho y proporcionar suficiente información para el soporte futuro. En mi opinión, este documento debe ser legible por una persona técnicamente agnóstica; no necesita ser "tonto", pero debe excluir la jerga y no confiar en el conocimiento asumido.

Los comentarios que rodean la fuente son lo primero que debe hacer. Esto asegura que haya un enlace directo a la documentación justo al lado del código. Si la documentación es muy complicada, considere publicar solo un resumen en los comentarios y luego un enlace a algún documento externo que contenga una descripción más completa de la arquitectura / algoritmo complejo. Sin embargo, si no es demasiado complicado, considere incluir toda la documentación en un solo lugar. Esto maximizará la probabilidad de que su código / documentación permanezca sincronizado y se lean juntos.

Documente el código en la medida en que su equipo / empresa lo necesite. Si un jr. Se requerirá que dev mantenga el código, es posible que tenga que entrar en detalles sobre algunas de las matemáticas. Esta es una decisión de administración y tienen que darle el tiempo necesario.

No creo que tenga que documentar tanto el código que tenga en cuenta que será reemplazado por un desarrollador menor. Si eso es una preocupación, debe tener tiempo para documentar.

No deberías tener que buscarlos en la web.