Was sind gute Möglichkeiten, wissenschaftliche Software zu dokumentieren?

Viele Male, wenn ich wissenschaftlichen Code von anderen Personen (oder gelegentlich sogar meiner eigenen Arbeit) geerbt habe oder auf ihn gestoßen bin, habe ich festgestellt, dass die Dokumentation entweder spärlich oder nicht vorhanden ist. Wenn ich Glück habe, sehe ich informative Kommentare. Wenn ich sehr viel Glück habe, gibt es sogar Doxygen-Kommentare und ein Doxyfile, sodass ich Funktionsschnittstellen und formatiertes HTML zu Rate ziehen kann. Wenn ich sehr viel Glück habe, gibt es ein PDF-Handbuch und Beispiele zusätzlich zu den Kommentaren zu Doxygen und der Quelldatei, und ich bin begeistert, weil es mein Leben viel, viel einfacher macht.

Welche Informationen und Tools sind für die Dokumentation von Quellcode hilfreich? Welche Informationen und Tools sind für die Dokumentation der Daten und Ergebnisse im Quellcode von wissenschaftlicher Software hilfreich?

Ich denke, dass die Dokumentation für wissenschaftliche Software in drei Kategorien unterteilt werden kann, die alle für ein umfassendes Verständnis erforderlich sind. Am einfachsten und gebräuchlichsten ist die Dokumentation einzelner Methoden. Dafür gibt es viele Systeme. Sie erwähnen doxygen , Python hat pydoc und in PETSc wir unser eigenes Paket haben Aussaat , die das erzeugt folgende .

Für jede Software, die über ein einfaches Dienstprogramm hinausgeht, benötigen Sie jedoch ein Handbuch. Dies bietet einen umfassenden Überblick über den Zweck des Pakets und die Integration der verschiedenen Funktionen, um diesen Zweck zu erreichen. Es hilft einem neuen Benutzer, seinen Code zu strukturieren, häufig anhand von Beispielen. In PETSc verwenden wir nur LaTeX für das Handbuch, aber das PyClaw- Paket verwendet das Sphinx- Framework, von dem ich sehr beeindruckt bin. Eine Sache, die wir im Säpaket implementiert haben, die ich sehr nützlich finde, ist die Verknüpfung zwischen Beispielcode und Funktionsdokumentation. Zum Beispiel dieses Beispiellöst die Bratu-Gleichung. Beachten Sie, wie Sie den Links für jeden benutzerdefinierten Typ oder Funktionsaufruf folgen und zur Dokumentation auf niedriger Ebene gelangen und wie diese Seiten auf Beispiele verweisen, in denen sie verwendet werden. Auf diese Weise lerne ich neue Funktionen kennen, die andere Projektmitarbeiter beitragen.

Ich denke, ein häufig übersehener Teil der Dokumentation ist die Entwicklerdokumentation. Es ist nicht ungewöhnlich, ein Dokument im Codestil und Anweisungen für die Interaktion mit dem Repository zu veröffentlichen. Es ist jedoch sehr selten, die vor der Implementierung getroffenen Entwurfsentscheidungen zu erläutern. Diese Entscheidungen sind immer mit Kompromissen verbunden, und die Situation in Bezug auf Hardware und Algorithmen wird sich im Laufe der Zeit notwendigerweise ändern. Ohne eine Erörterung der überprüften Kompromisse und der Begründung für bestimmte Entwurfsentscheidungen müssen spätere Programmierer den gesamten Prozess selbst neu erstellen. Ich denke, dies ist ein großes Hindernis für die erfolgreiche Wartung und Verbesserung alter Codes, wenn die ursprünglichen Entwickler nicht mehr verantwortlich sind.

In-Code-Dokumentation

Am wichtigsten ist es, die Dokumentationsfunktionen in der von Ihnen gewählten Entwicklungsumgebung zu verwenden, dh pydoc für Python, Javadoc in Java oder XML-Kommentare in C #. Dies erleichtert das Schreiben der Dokumentation gleichzeitig mit dem Schreiben des Codes.

Wenn Sie darauf vertrauen, dass Sie später zurückkehren und die Dinge dokumentieren, kommen Sie vielleicht nicht daran vorbei, aber wenn Sie es tun, während Sie den Code schreiben, ist das, was dokumentiert werden muss, frisch in Ihrem Kopf. C # bietet sogar die Möglichkeit, eine Kompilierungswarnung auszugeben, wenn die XML-Dokumentation unvollständig oder mit dem tatsächlichen Code nicht konsistent ist.

Tests als Dokumentation

Ein weiterer wichtiger Aspekt ist eine gute Integration und Unit-Tests.

Oft konzentriert sich die Dokumentation darauf, was Klassen und Methoden für sich tun, und überspringt, wie sie zur Lösung Ihres Problems zusammen verwendet werden. Tests stellen diese häufig in einen Zusammenhang, indem sie zeigen, wie sie miteinander interagieren.

In ähnlicher Weise weisen Unit-Tests häufig explizit auf externe Abhängigkeiten hin, durch die die Dinge nachgebildet werden müssen.

Ich finde auch, dass ich mit testgetriebener Entwicklung Software schreibe, die einfacher zu bedienen ist, weil ich sie von Anfang an benutze. Mit einem guten Test-Framework ist es oft dasselbe, Code einfacher zu testen und benutzerfreundlich zu machen.

Dokumentation auf höherer Ebene

Schließlich müssen Sie noch die Systemebene und die Architekturdokumentation berücksichtigen. Viele befürworten das Schreiben einer solchen Dokumentation in einem Wiki oder die Verwendung von Word oder einem anderen Textverarbeitungsprogramm, aber für mich ist der beste Ort für eine solche Dokumentation neben dem Code ein Nur-Text-Format, das für das Versionskontrollsystem geeignet ist.

Genau wie bei der In-Code-Dokumentation ist es wahrscheinlicher, dass Sie Ihre Dokumentation auf höherer Ebene in Ihrem Code-Repository auf dem neuesten Stand halten. Sie haben auch den Vorteil, dass Sie beim Herausziehen der Version XY des Codes auch die Version XY der Dokumentation erhalten. Wenn Sie ein VCS-freundliches Format verwenden, bedeutet dies außerdem, dass es einfach ist, Ihre Dokumentation wie Ihren Code zu verzweigen, zu vergleichen und zusammenzuführen.

Ich mag reStructuredText (rst) sehr , da es mit Sphinx einfach ist, sowohl HTML-Seiten als auch PDF-Dokumente daraus zu erstellen. Es ist viel freundlicher als LaTeX , kann aber auch LaTeX-mathematische Ausdrücke enthalten, wenn Sie sie benötigen.

Ich werde mit fast jedem Punkt, den Faheem anführt , Einwände erheben . Speziell:

1 / "Ich halte es für unrealistisch, von wissenschaftlichen Entwicklern zu erwarten, dass sie viel Zeit damit verbringen, ihre Software zu dokumentieren". Dies ist ein Rezept für ein fehlgeschlagenes Projekt, das bald niemand mehr verwenden kann, der keinen Zugriff auf die primären Entwickler hat. Aus gutem Grund verfügen die großen wissenschaftlichen Computer-Bibliotheken (z. B. PETSc oder deal.II) über eine umfangreiche Dokumentation, die über 1000 Seiten oder mehr umfasst. Sie können keine große Benutzergemeinschaft haben, wenn Sie keine umfassende Dokumentation haben. Ich stimme jedoch zu, dass Beispielcodes einfach sein und sich auf ein einziges Konzept konzentrieren müssen.

2 / "Die Autoren sollten erwägen, gegebenenfalls ein Papier zur Veröffentlichung zu verfassen." Das ist in der Praxis oft nicht möglich. Man kann Arbeiten zu Konzepten und Algorithmen schreiben, aber nicht zu Schnittstellen und anderen Entwurfsentscheidungen. Leser solcher Papiere werden eine Vorstellung davon bekommen, wie die Implementierung es macht; Benutzer der Implementierung müssen wissen, welche Funktionen aufgerufen werden sollen, was die Argumente usw. bedeuten. Als Benutzer kann man die meiste Zeit ohne die ersteren leben und eine Bibliothek einfach als Black Box betrachten, aber man kann nicht ohne sie auskommen Schnittstelleninformationen.

Das ist eine gute Frage. In erster Näherung sollte der Code versuchen, sich selbst zu dokumentieren. So zum Beispiel, wenn die Software - Befehlszeile ist, sollten Sie in der Lage sein , zu tun executable --helpoder executable -hoder sogar executable(wenn die ausführbare Datei tut nichts ohne Argumente) und hat eine kurze Verwendungsmeldung Rückkehr.

Zweitens halte ich es für unrealistisch, von wissenschaftlichen Entwicklern zu erwarten, dass sie viel Zeit damit verbringen, ihre Software zu dokumentieren, und schlage daher vor, sie einfach zu halten. Ein kurzes Texthandbuch mit den grundlegenden Methoden und Optionen sowie kommentiertem Arbeiten und TestenAnwendungsbeispiele, die von einfach zu komplex gestaffelt sind (Anwendungsbeispiele sind sehr wichtig und werden häufig vernachlässigt), sind erheblich besser als nichts und viel mehr als die meisten wissenschaftlichen Softwareangebote. Ich möchte auch einen Pet Peeve über Anwendungsbeispiele hinzufügen. Einfach bedeutet einfach. Das heißt, wenn Sie versuchen, eine Methode zu veranschaulichen, fügen Sie nicht zehn irrelevante Konzepte oder Methoden hinzu, um den Leser zu verwirren. Halten Sie es einfach und kommentieren Sie, damit der Leser weiß, was das Beispiel tun soll. Ich würde auch vorschlagen, die manuellen Verwendungsbeispiele in eine Testsuite zu integrieren, damit sie weiter funktionieren, wenn der Code geändert wird. Eigentlich weiß ich nicht, wie ich das gut machen soll. Zögern Sie nicht, mich zu unterrichten. Wenn die Entwickler ausgefallener werden möchten, können sie sicher nette Markup-Sprachen verwenden und so weiter. Fügen Sie Manpages hinzu und so weiter.

Drittens sollten die Autoren erwägen, gegebenenfalls ein Papier zur Veröffentlichung zu verfassen. Dies würde in der Regel Entwurfsentscheidungen ansprechen und eine umfassendere Perspektive auf die Software bieten als ein Handbuch oder dies kann erwartet werden. Dies würde sich mit der Dokumentation von Entwurfsentscheidungen befassen, über die @Matt sprach.

Die wichtigste Dokumentation ist natürlich der Code selbst, der bei Bedarf kommentiert werden sollte. Dies setzt voraus, dass der Code freie Software ist. Wenn dies nicht der Fall ist, ist es als wissenschaftliche Software wesentlich weniger nützlich (möchten Sie wirklich eine Black Box verwenden, in der Sie nicht sehen können, wie die Methoden implementiert sind?) Und ich würde es nicht verwenden.

Zur Beantwortung Ihrer Frage, wie Daten und Ergebnisse dokumentiert werden, empfehle ich etwa das Doctest-Modul von Python . Auf diese Weise können Sie Tutorials oder Tests auf eine Weise schreiben, die automatisch validiert werden kann.

Wenn Sie sich für Alphabetisierung interessieren, schauen Sie sich org-babel an . Es ist Teil des org-Modus in Emacs und bietet Ihnen daher eine Vielzahl von Exportoptionen (LaTeX, PDF, HTML, ODT) für die Dokumentation. Emacs kann Bilder im Puffer anzeigen und Sie können mathematische Gleichungen in LaTeX-Syntax schreiben, sodass Sie sich nicht auf reine Textdokumentation beschränken müssen.

Eine Dokumentation, die automatisch aus Ihrem Quellcode abgeleitet wird, ist ein wesentlicher Bestandteil für eine aktuelle, dh korrekte Dokumentation. Ich kann nicht zählen, wie oft ich Dokumentation gesehen habe, die Jahre hinter dem Quellcode liegt, weil die Entwickler der Dokumentation gegenüber apathisch sind. Die einfache Lösung besteht darin, es Programmierern zu erleichtern, Dokumentation zusammen mit neuem Code zur selben Zeit an derselben Stelle zu schreiben, und nicht als nachträgliche Anstrengung, die unweigerlich zugunsten glorreicherer Aktivitäten nachrangig behandelt wird.

Wenn ich gezwungen bin zu wählen, hätte ich lieber detaillierte und genaue (dh aktuelle) Quellcode-Kommentare, aber keine Bedienungsanleitung, als eine veraltete Bedienungsanleitung, die voller falscher Informationen ist.

In Python gibt es die Tools pep8 und pep257, die fehlende oder fehlerhafte Dokumentation melden. elpy for Emacs wird sich auch über fehlende Dokumentation beschweren. Die Numpy-Docstring-Konventionen mit reStructuredText sollten beachtet werden . Der Test mit pep8, pep257 und doctest kann so eingerichtet werden, dass py.test und tox automatisch ausgeführt werden.