¿Cuáles son buenas maneras de documentar software científico?

Muchas veces, cuando heredé o me encontré con un código científico escrito por otras personas (u ocasionalmente, incluso con mi propio trabajo), noté que la documentación es escasa o inexistente. Si tengo suerte, veo comentarios informativos. Si tengo mucha suerte, incluso hay comentarios de Doxygen y un Doxyfile para que tenga interfaces de funciones y algunos HTML formateados para consultar. Si tengo mucha suerte, hay un manual en PDF y ejemplos además de los comentarios de Doxygen y del archivo fuente, y estoy extasiado, porque me facilita mucho la vida.

¿Qué información y herramientas son útiles para documentar el código fuente? Para el caso, ¿qué información y herramientas son útiles para documentar los datos y resultados que acompañan a ese código fuente, en el caso del software científico?

Creo que la documentación para el software científico se puede dividir en tres categorías, todas las cuales son necesarias para una comprensión completa. Lo más fácil y lo más común es la documentación de métodos individuales. Hay muchos sistemas para esto. Usted menciona doxygen , Python tiene pydoc , y en PETSc tenemos nuestra propia siembra de paquetes que genera lo siguiente .

Sin embargo, para cualquier pieza de software que vaya más allá de una simple utilidad, necesita un manual. Esto proporciona una vista de alto nivel del propósito del paquete y cómo se integran sus diferentes funcionalidades para lograr este propósito. Ayuda a un nuevo usuario a estructurar su código, a menudo mediante el uso de ejemplos. En PETSc, solo usamos LaTeX para el manual, pero el paquete PyClaw usa el marco Sphinx con el que estoy muy impresionado. Una cosa que hemos implementado en el paquete de siembra que encuentro muy útil es el enlace entre el código de ejemplo y la documentación de la función. Por ejemplo, este ejemploresuelve la ecuación de Bratu. Observe cómo puede seguir los enlaces para cualquier tipo personalizado o llamada de función y acceder a la documentación de bajo nivel, y cómo esas páginas enlazan con ejemplos que los usan. Así es como aprendo sobre la nueva funcionalidad que otras personas en el proyecto contribuyen.

Una parte frecuentemente olvidada de la documentación, creo, es la documentación del desarrollador. No es raro publicar un documento de estilo de codificación e instrucciones para interactuar con el repositorio. Sin embargo, es muy raro explicar las decisiones de diseño tomadas antes de la implementación. Estas decisiones siempre implican compensaciones, y la situación con respecto al hardware y los algoritmos necesariamente cambiará con el tiempo. Sin una discusión de las compensaciones revisadas y la justificación de decisiones de diseño particulares, los programadores posteriores deben recrear todo el proceso por su cuenta. Creo que este es un impedimento importante para el mantenimiento exitoso y la mejora de los códigos antiguos cuando los desarrolladores originales ya no están a cargo.

Documentación en código

Lo más importante es utilizar las funciones de documentación en el entorno de desarrollo elegido, por lo que significa pydoc para python, javadoc en java o comentarios xml en C #. Esto facilita la escritura de la documentación al mismo tiempo que escribe 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 necesitan ser burladas .

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 el nivel del sistema y la documentación arquitectónica. Muchos recomendarían 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 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 ramificar, diferenciar y fusionar su documentación, al igual que su código.

Me gusta bastante reStructuredText (primero) , ya que es fácil producir tanto páginas html como documentos pdf usando sphinx , y es mucho más amigable que LaTeX , pero aún puede incluir expresiones matemáticas de LaTeX cuando las necesite.

Voy a objetar casi todos los puntos que Faheem hace . Específicamente:

1 / "Creo que no es realista esperar que los desarrolladores científicos pasen mucho tiempo documentando su software". Esta es una receta para un proyecto fallido que pronto nadie podrá usar si no tiene acceso a los desarrolladores principales. Es por una buena razón que las grandes bibliotecas de computación científica (por ejemplo, PETSc, o deal.II) tienen una amplia documentación que se extiende a miles de páginas o más. No puede tener una comunidad de usuarios considerable si no tiene una documentación extensa. Sin embargo, estaré de acuerdo en que los códigos de ejemplo deben ser simples y centrados en un solo concepto.

2 / "los autores deberían considerar escribir un artículo para publicación, si corresponde". Eso a menudo no es posible en la práctica. Se pueden escribir documentos sobre conceptos y algoritmos, pero no sobre interfaz y otras decisiones de diseño. Los lectores de dichos documentos tendrán una idea de lo que hace la implementación; los usuarios de la implementación necesitarán saber qué funciones llamar, qué significan los argumentos, etc. Como usuario, la mayoría de las veces se puede vivir sin el primero y simplemente considerar una biblioteca como una caja negra, pero no se puede prescindir de ella. Información de la interfaz.

Esta es una buena pregunta. Para una primera aproximación, el código debe intentar autodocumentarse. Así, por ejemplo, si el software es la línea de comandos, debe ser capaz de hacer executable --helpo executable -hincluso executable(si el ejecutable no hace nada sin argumentos), y tienen un mensaje de retorno uso breve.

En segundo lugar, creo que no es realista esperar que los desarrolladores científicos pasen una gran cantidad de tiempo documentando su software, por lo que sugiero que sea simple. Un breve manual de texto con los métodos y opciones básicos y trabajo anotado y probadoLos ejemplos de uso, graduados de simples a más complejos (los ejemplos de uso son muy importantes y frecuentemente descuidados) es considerablemente mejor que nada y mucho más que la mayoría de los programas científicos ofrecen. También me gustaría agregar un motivo favorito sobre ejemplos de uso. Simple significa simple. Eso significa que si está tratando de ilustrar un método, no agrega diez conceptos o métodos extraños para confundir al lector. Mantenlo simple y anota para que el lector sepa lo que se supone que está haciendo el ejemplo. También sugeriría vincular los ejemplos de uso manual en un conjunto de pruebas de alguna manera para que continúen funcionando cuando se cambie el código. En realidad no sé cómo hacer esto de una manera agradable, así que siéntete libre de educarme. Si los desarrolladores quieren ser más sofisticados, asegúrese de que puedan usar buenos lenguajes de marcado, etc., agregue páginas de manual, etc.

En tercer lugar, los autores deberían considerar escribir un artículo para su publicación, si corresponde. Esto generalmente abordaría las decisiones de diseño y daría una perspectiva de más alto nivel sobre el software que un manual, o se puede esperar que lo haga. Esto abordaría la documentación de las decisiones de diseño de las que @Matt estaba hablando.

Por supuesto, la documentación más importante de todas es el código en sí, que debe comentarse según sea necesario. Esto supone que el código es software libre. Si no lo es, entonces es sustancialmente menos útil como software científico (¿realmente desea usar un cuadro negro donde no puede ver cómo se implementan los métodos?) Y por mi parte no lo usaría.

Para responder a su pregunta sobre cómo documentar los datos y los resultados, recomendaría algo como el módulo doctest de Python . Esto le permite escribir tutoriales o pruebas de una manera que se pueda validar automáticamente.

Si está interesado en la programación alfabetizada, eche un vistazo a org-babel . Es parte del modo org en Emacs y, por lo tanto, le ofrece una amplia gama de opciones de exportación (LaTeX, PDF, HTML, ODT) para la documentación. Emacs puede mostrar imágenes dentro del búfer y le permite escribir ecuaciones matemáticas en la sintaxis de LaTeX para que no tenga que limitarse a la documentación de texto sin formato.

La documentación que se deriva automáticamente de su código fuente es un componente esencial para tener una documentación actualizada, es decir, correcta. No puedo contar cuántas veces he visto documentación que está años atrás del código fuente debido a la apatía del desarrollador hacia la documentación. La solución fácil es facilitar que los programadores escriban documentación junto con el nuevo código en el mismo lugar al mismo tiempo, en lugar de como un esfuerzo posterior que inevitablemente será priorizado en favor de actividades más gloriosas.

Si me veo obligado a elegir, prefiero tener comentarios detallados y precisos (es decir, actuales) del código fuente, pero ningún manual de usuario que un manual de usuario desactualizado que esté lleno de información incorrecta.

En Python existen las herramientas pep8 y pep257 que informarán la documentación faltante o con formato incorrecto. Elpy para Emacs también se quejará de la falta de documentación. Las convenciones de Numpy docstring con reStructuredText son buenas para seguir. La prueba con pep8, pep257 y doctest se puede configurar con py.test y tox ejecutándose automáticamente.