Wo sollte ein Programmierer die erweiterte Logik hinter dem Code erklären?

Ich habe einige quantitative Bibliotheken in C # entwickelt, in denen es wichtig ist, nicht nur die klassischen Informationen zu verstehen, die zu den XMLDoc-Kommentaren gehören (die grundlegende Informationen mit der Methodensignatur enthalten), sondern auch die mathematischen Formeln, die in den Methoden verwendet werden.

Daher möchte ich in der Lage sein, dem Code eine erweiterte Dokumentation hinzuzufügen, die beispielsweise Latexformeln, Grafiken usw. enthalten kann.

Denken Sie, dass solche Informationen in die API-Dokumentation aufgenommen werden sollten?

Oder sollte es zum Beispiel in einem Entwickler-Blog enthalten sein?

Gibt es gängige Tools, die normalerweise für diese Art von Zwecken verwendet werden?

Je näher Sie die Dokumentation am Code halten, desto wahrscheinlicher ist es für mich, auf dem neuesten Stand zu bleiben, und desto nützlicher ist sie.

Aus diesem Grund versuche ich, die gesamte Dokumentation im selben Repository wie den Code zu speichern, auch die Benutzerhandbücher, und sie in einem Nur-Text-Format zu speichern, das von einem Revisionskontrollsystem problemlos verwaltet werden kann.

In-Code-Dokumentation

Es sieht so aus, als hätten Sie dieses bereits behandelt, aber es ist wichtig zu bedenken, dass die tatsächliche Verwendung der Dokumentationsfunktionen in der von Ihnen ausgewählten Entwicklungsumgebung ( pydoc für Python, javadoc in Java oder XML-Kommentare in C #) die wichtigste Dokumentationstechnik ist. Sie machen es einfach, die Dokumentation gleichzeitig mit dem Schreiben des Codes zu schreiben.

Wenn Sie sich darauf verlassen, dass Sie später wiederkommen und Dinge dokumentieren, kommen Sie möglicherweise nicht dazu, aber wenn Sie dies tun, während Sie den Code schreiben, ist das, was dokumentiert werden muss, in Ihrem Kopf frisch. C # hat sogar die Möglichkeit, eine Kompilierungswarnung auszugeben, wenn die XML-Dokumentation unvollständig ist oder nicht mit dem tatsächlichen Code übereinstimmt.

Tests als Dokumentation

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

Oft konzentriert sich die Dokumentation darauf, was Klassen und Methoden isoliert tun, und überspringt, wie sie zusammen verwendet werden, um Ihr Problem zu lösen. Tests stellen diese häufig in einen Kontext, indem sie zeigen, wie sie miteinander interagieren.

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

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

Übergeordnete Dokumentation

Schließlich gibt es was zu tun auf Systemebene, Architektur, Entwickler und möglicherweise auch Endbenutzerdokumentation. Viele würden befürworten, eine solche Dokumentation in einem Wiki zu schreiben oder Word oder ein anderes Textverarbeitungsprogramm zu verwenden, aber für mich ist der beste Ort für eine solche Dokumentation auch neben dem Code in einem Nur-Text-Format, das für das Versionskontrollsystem geeignet ist.

Genau wie bei der In-Code-Dokumentation ist es wahrscheinlicher, dass Sie Ihre übergeordnete Dokumentation auf dem neuesten Stand halten, wenn Sie sie in Ihrem Code-Repository speichern. Sie erhalten 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 genau wie Ihr Code einfach zu verzweigen, zu unterscheiden und zusammenzuführen ist.

Ich mag rst sehr , da es einfach ist, sowohl HTML-Seiten als auch PDF-Dokumente daraus zu erstellen, viel freundlicher als LaTeX ist und dennoch LaTeX-Mathematikausdrücke enthalten kann, wenn Sie sie benötigen.

Wenn ich hochmathematischen Code schreibe, finde ich es auch nützlich, einige wxmaxima- Dokumente in meinem Projekt-Repository zu haben. Da es sich um einfachen Text handelt, können diese auch gut verzweigt, differenziert und zusammengeführt werden. Die Verwendung eines Computeralgebrasystems kann Ihnen jedoch dabei helfen, die Konsistenz Ihrer Formeln zu überprüfen und sie zu dokumentieren.

Sie können diese Dokumentation in die XML-Kommentare aufnehmen und mit doxygen LaTeX-Handbücher, Webseiten und andere Dokumente daraus erstellen . Verwenden Sie die <remarks>und <example>-Elemente für die erweiterte Prosa.

Ich würde externe Dokumentation verwenden, wenn Sie Klassendiagramme, Diagramme, Formeln, Bilder usw. einfügen müssen, um zu erklären, wie Ihre Bibliotheken funktionieren. Fügen Sie diese externe Dokumentation als Teil Ihrer Bibliotheksversionen in einem von Ihnen als geeignet erachteten Format (LaTeX oder auf andere Weise) hinzu. Wenn Sie möchten, können Sie in Ihrem Code auf dieses Dokument verweisen (z. B. "Weitere Informationen finden Sie in der" Readme "-Dokumentation.").

Ich glaube, der Schlüssel ist die Konsistenz . Wenn Sie die Methoden konsistent mit Kommentaren versehen haben, die beispielsweise von Doxygen extrahiert werden können, ist es nur sinnvoll, auch die erweiterte Logikbeschreibung dort aufzunehmen, da dort andere Entwickler am wahrscheinlichsten suchen. Das plötzliche Verweisen des Entwicklers auf ein anderes Dokument erscheint unnötig und verwirrt die Entwickler nur.

Wenn die Beschreibung des gesamten Programms jedoch an anderer Stelle angegeben ist, sollten Sie sich daran halten und dort die erweiterte Logikbeschreibung angeben.

Wenn Sie der Meinung sind, dass die Innereien einer Methode in Ihrer API dokumentiert werden müssen, haben Sie die Schnittstelle wahrscheinlich nicht sehr gut definiert / modularisiert.

Eine gut geschriebene API sollte den Programmierer nicht dazu zwingen, die Funktionsweise der Interna zu verstehen. Indem Sie die Funktionsweise unnötig dokumentieren, unterbrechen Sie die Abstraktionsschicht und binden sich in eine bestimmte Implementierung ein, was ebenfalls nicht gut ist.