Quels sont les bons moyens de documenter un logiciel scientifique?

Souvent, quand j'ai hérité ou rencontré du code scientifique écrit par d'autres personnes (ou parfois même par mon propre travail), j'ai remarqué que la documentation était soit rare, soit inexistante. Si j'ai de la chance, je vois des commentaires informatifs. Si j'ai beaucoup de chance, il y a même des commentaires Doxygen et un fichier Doxy, ce qui me permet de consulter des interfaces de fonction et du code HTML formaté. Si je suis extrêmement chanceux, il existe un manuel au format PDF et des exemples en plus des commentaires de Doxygen et du fichier source. Je suis extatique, car cela me rend la vie beaucoup plus facile.

Quelles informations et quels outils sont utiles pour documenter le code source? D'ailleurs, quels informations et outils sont utiles pour documenter les données et les résultats qui accompagnent ce code source, dans le cas d'un logiciel scientifique?

Je pense que la documentation des logiciels scientifiques peut être divisée en trois catégories, qui sont toutes nécessaires pour une compréhension complète. Le plus simple et le plus courant est la documentation de chaque méthode. Il existe de nombreux systèmes pour cela. Vous mentionnez doxygen , Python a pydoc et, en PETSc, nous avons notre propre semis de paquets qui génère les éléments suivants .

Cependant, pour tout logiciel dépassant un simple utilitaire, vous avez besoin d’un manuel. Ceci fournit une vue de haut niveau de l'objectif du package et de la manière dont ses différentes fonctionnalités s'intègrent pour atteindre cet objectif. Cela aide un nouvel utilisateur à structurer son code, souvent à l'aide d'exemples. Dans PETSc, nous utilisons simplement LaTeX pour le manuel, mais le paquet PyClaw utilise le framework Sphinx qui me impressionne beaucoup. Une des choses que nous avons implémentées dans le package de semis et que je trouve très utiles est le lien entre l’exemple de code et la documentation des fonctions. Par exemple, cet exemplerésout l'équation de Bratu. Remarquez comment vous pouvez suivre les liens pour tout appel de type ou de fonction personnalisé et accéder à la documentation de bas niveau, et comment ces pages renvoient aux exemples les utilisant. C’est ainsi que j’apprends la nouvelle fonctionnalité proposée par d’autres personnes du projet.

Je pense que la documentation destinée aux développeurs est une partie de la documentation souvent négligée. Il n'est pas rare de publier un document de style codage et des instructions pour interagir avec le référentiel. Cependant, il est très rare d'expliquer les décisions de conception prises avant la mise en œuvre. Ces décisions impliquent toujours des compromis et la situation en ce qui concerne le matériel et les algorithmes évoluera nécessairement dans le temps. Sans une discussion des compromis examinés et de la justification de décisions de conception particulières, les programmeurs ultérieurs sont obligés de recréer le processus dans son intégralité. Je pense que cela constitue un obstacle majeur au succès de la maintenance et de l'amélioration des anciens codes lorsque les développeurs d'origine ne sont plus en charge.

Documentation en code

Le plus important est d’utiliser les installations de documentation dans l’environnement de développement choisi, ce qui signifie pydoc pour python, javadoc en java ou des commentaires xml en C #. Cela facilite la rédaction de la documentation en même temps que l’écriture du code.

Si vous comptez revenir et documenter les choses plus tard, vous ne le comprendrez peut-être pas, mais si vous le faites pendant que vous écrivez le code, alors ce qui doit être documenté sera frais dans votre esprit. C # a même la possibilité d'émettre un avertissement de compilation si la documentation XML est incomplète ou incompatible avec le code réel.

Tests en tant que documentation

Un autre aspect important est une bonne intégration et des tests unitaires.

Souvent, la documentation se concentre sur ce que les classes et les méthodes font de manière isolée, en ignorant comment elles sont utilisées ensemble pour résoudre votre problème. Les tests les mettent souvent en contexte en montrant comment ils interagissent les uns avec les autres.

De même, les tests unitaires soulignent souvent les dépendances externes de manière explicite au moyen desquelles des éléments doivent être simulés .

Je constate également que, grâce au développement piloté par les tests, j'écris un logiciel plus facile à utiliser, car je l'utilise dès le départ. Avec un bon framework de test, rendre le code plus facile à tester et à le rendre facile à utiliser est souvent la même chose.

Documentation de niveau supérieur

Enfin, il y a quoi faire à propos de la documentation au niveau du système et de l'architecture. Beaucoup préconiseraient d'écrire une telle documentation sur un wiki ou d'utiliser Word ou un autre logiciel de traitement de texte, mais pour moi, le meilleur endroit pour une telle documentation est à côté du code, dans un format de texte brut adapté au système de contrôle de version.

Comme avec la documentation intégrée au code, si vous stockez votre documentation de niveau supérieur dans votre référentiel de code, vous aurez plus de chances de la maintenir à jour. Vous bénéficiez également de l'avantage que lorsque vous extrayez la version XY du code, vous obtenez également la version XY de la documentation. En outre, si vous utilisez un format convivial VCS, cela signifie qu'il est facile de créer des branches, de comparer et de fusionner votre documentation, tout comme votre code.

J'aime beaucoup reStructuredText (rst) , car il est facile de produire à la fois des pages html et des documents pdf à l'aide de sphinx . Il est beaucoup plus convivial que LaTeX , mais peut quand même inclure des expressions mathématiques LaTeX lorsque vous en avez besoin.

Je vais faire objection à presque tous les arguments de Faheem . Plus précisément:

1 / "Je pense qu’il est irréaliste d’attendre des développeurs scientifiques qu’ils consacrent beaucoup de temps à la documentation de leurs logiciels". Ceci est une prescription pour un projet en échec que bientôt personne ne pourra utiliser qui n'a pas accès aux développeurs principaux. C’est pour une bonne raison que les grandes bibliothèques d’informatique scientifique (p.ex. PETSc ou deal.II) disposent d’une documentation étendue pouvant aller jusqu’à 1 000 pages ou plus. Vous ne pouvez pas avoir une communauté d'utilisateurs importante si vous n'avez pas une documentation complète. Je conviens toutefois que les exemples de codes doivent être simples et centrés sur un seul concept.

2 / "Les auteurs devraient envisager de rédiger un article pour publication le cas échéant". C'est souvent impossible dans la pratique. On peut rédiger des articles sur les concepts et les algorithmes, mais pas sur les décisions d’interface et autres. Les lecteurs de ces documents auront une idée de ce que la mise en œuvre fait; les utilisateurs de l'implémentation doivent savoir quelles fonctions appeler, ce que signifient les arguments, etc. En tant qu'utilisateur, on peut généralement vivre sans l'ancien et simplement considérer une bibliothèque comme une boîte noire, mais on ne peut pas s'en passer. informations d'interface.

C'est une bonne question. En première approximation, le code doit essayer de se documenter lui-même. Ainsi, par exemple, si le logiciel est en ligne de commande, vous devriez être capable de faire executable --helpou executable -hmême executable(si l'exécutable ne fait rien sans arguments) et de recevoir un bref message d'utilisation.

Deuxièmement, je pense qu'il est irréaliste de s'attendre à ce que les développeurs scientifiques consacrent beaucoup de temps à la documentation de leurs logiciels. Je suggère donc de garder les choses simples. Un bref manuel avec les méthodes de base et les options, ainsi que des notes de travail et testéesdes exemples d'utilisation, allant du plus simple au plus complexe (les exemples d'utilisation sont très importants et souvent négligés) sont bien meilleurs que rien et bien plus que la plupart des logiciels scientifiques. J'aimerais également ajouter une bête noire sur les exemples d'utilisation. Simple signifie simple. Cela signifie que si vous essayez d’illustrer une méthode, vous n’ajoutez pas dix concepts ou méthodes superflus pour dérouter le lecteur. Restez simple et annotez pour que le lecteur sache ce que l'exemple est censé faire. Je suggérerais également de relier les exemples d'utilisation manuelle à une suite de tests afin qu'ils continuent de fonctionner lorsque le code est modifié. Je ne sais pas vraiment comment faire cela gentiment, alors n'hésitez pas à me renseigner. Si les développeurs veulent avoir plus de fantaisie, ils peuvent sûrement utiliser de beaux langages de balisage, etc., ajouter des pages de manuel, etc.

Troisièmement, les auteurs devraient envisager de rédiger un article pour publication, le cas échéant. Cela résoudrait généralement les problèmes de conception et donnerait une perspective de haut niveau sur le logiciel par rapport à un manuel. Cela traiterait de la documentation des décisions de conception dont parlait @Matt.

Bien entendu, la documentation la plus importante est le code lui-même, qui doit être commenté au besoin. Cela suppose que le code est un logiciel libre. Si ce n'est pas le cas, il est nettement moins utile en tant que logiciel scientifique (voulez-vous vraiment utiliser une boîte noire où vous ne pouvez pas voir comment les méthodes sont mises en œuvre?) Et moi, je ne l'utiliserais pas.

Pour répondre à votre question sur la manière de documenter les données et les résultats, je recommanderais quelque chose comme le module doctest de Python . Cela vous permet de rédiger des tutoriels ou des tests d’une manière pouvant être automatiquement validée.

Si vous êtes intéressé par la programmation alphabète, jetez un coup d'œil à org-babel . Il fait partie du mode org dans Emacs et vous offre donc un large éventail d’options d’exportation (LaTeX, PDF, HTML, ODT) pour la documentation. Emacs peut afficher des images dans la mémoire tampon et vous permettre d’écrire des équations mathématiques en syntaxe LaTeX afin que vous n’ayez pas à vous limiter à la documentation en texte brut.

La documentation qui est automatiquement dérivée de votre code source est un élément essentiel pour avoir une documentation à jour, c'est-à-dire correcte. Je ne peux pas compter le nombre de fois où j'ai vu de la documentation avec des années de retard sur le code source en raison de l'apathie des développeurs à l'égard de la documentation. La solution simple consiste à aider les programmeurs à écrire de la documentation avec le nouveau code au même endroit et au même moment, plutôt que comme un effort a posteriori qui sera inévitablement dé-hiérarchisé au profit d’activités plus glorieuses.

Si je suis obligé de choisir, je préférerais avoir des commentaires détaillés et précis (c.-à-d. Actuels) sur le code source, mais pas de manuel de l'utilisateur, si ce n'est un manuel de l'utilisateur obsolète qui regorge d'informations erronées.

En Python, il existe les outils pep8 et pep257 qui signaleront la documentation manquante ou mal formée. Elpy pour Emacs se plaindra également de la documentation manquante. Les conventions Numpy docstring avec reStructuredText sont bonnes à suivre. Les tests avec pep8, pep257 et doctest peuvent être configurés avec py.test et tox s'exécutant automatiquement.