Dokumentation der mathematischen Logik im Code

Manchmal, wenn auch nicht oft, muss ich mathematische Logik in meinen Code einfügen. Die verwendeten Konzepte sind meist sehr einfach, aber der resultierende Code ist nicht - viele Variablen mit unklarem Zweck und einige Operationen mit nicht so offensichtlicher Absicht. Ich will damit nicht sagen , dass der Code nicht lesbar oder wartbaren ist, nur , dass es waaaay härter als das tatsächliche mathematische Problem ist zu verstehen. Ich versuche, die Teile zu kommentieren, die am schwersten zu verstehen sind, aber es gibt das gleiche Problem wie beim Codieren - Text hat nicht die Ausdruckskraft von Mathematik .

Ich suche nach einer effizienteren und verständlicheren Methode, um die Logik hinter einem Teil des komplexen Codes zu erklären, vorzugsweise im Code selbst. Ich habe TeX in Betracht gezogen - die Dokumentation zu schreiben und sie getrennt vom Code zu generieren. Aber dann müsste ich TeX lernen und die Dokumentation wird nicht im Code selbst sein. Eine andere Sache, an die ich gedacht habe, ist, ein Bild der mathematischen Notationen, Gleichungen und Diagramme zu machen, die auf Papier / Whiteboard geschrieben sind, und es in Javadoc aufzunehmen.

Gibt es einen einfacheren und klareren Weg?

PS Wenn Sie den Variablen beschreibende Namen geben ( timeOfFirstEventanstelle von t1), wird der Code ausführlicher und noch schwieriger zu lesen.

Unter solchen Umständen ist es richtig, den Algorithmus, die Formel oder was auch immer mit genau den gleichen Variablennamen wie in der primären realen Quelle zu implementieren (soweit die Programmiersprache dies zulässt) und einen kurzen Kommentar darüber zu haben so etwas wie "Levenshtein-Entfernungsberechnung wie in [Knuth1968] beschrieben", wo das Zitat auf eine leicht zugängliche Beschreibung der Mathematik verweist.

(Wenn Sie nicht haben eine solche Referenz, aber Ihre Mathe ist gesund und nützlich, vielleicht sollten Sie es für sich selbst zu veröffentlichen. Gerade Sayin.)

Wenn ich solche Algorithmen implementieren musste, gibt es ein paar Dinge, die ich tue.

1. Isolieren Sie den Algorithmus so weit wie möglich auf seine eigene Methode oder vorzugsweise Klasse. Mein aktuelles Projekt hat eine eigene äquivalente MathKlasse, um komplexe Algorithmen hinzuzufügen.

2. Geben Sie eine Zusammenfassung dessen, was der Algorithmus tun soll, einschließlich aller gebräuchlichen Akronyme oder Kurzreferenzen auf den Begriff. Ich mache das in der Methode selbst, also lebt es mit dem Code.

3. Stellen Sie eine technische / mathematische Zusammenfassung des Algorithmus bereit und geben Sie alle mir bekannten externen Referenzen an. Auch dies mache ich mit der Methode selbst, damit es eine bessere Chance hat, relevant zu bleiben. Klartext ist in diesem Fall nicht besonders gut, daher zitiere ich den mathematischen Begriff so gut ich kann und erkläre ihn in einem Kommentar in Klammern. Beispielsweise, x^y (x raised to the power y)

4. Dokumentieren Sie, wie ich den Algorithmus in Komponenten zerlege, und geben Sie an, was jede Variable im Algorithmus darstellt. z.B.t1 is time of first event

5. Code den Algorithmus und kommentiere die komplexen Teile. Im Wesentlichen werde ich überall dort einen Kommentar hinzufügen, wo ich einen Schritt unternehme, der im Algorithmus selbst nicht offensichtlich oder unkompliziert war. Ich stelle insbesondere sicher, dass ich nicht offensichtliche Verknüpfungen kommentiere und erkläre, warum sie in Ordnung sind, die ich innerhalb der Implementierung verwenden kann.

6. Schreiben Sie einige Komponententests auf, die die Funktionsweise des Algorithmus bestätigen.

Wenn es wirklich, wirklich, wirklich komplex ist, dann gebe ich mich damit ab, dass ich den Code für den Rest meiner Zeit für dieses Projekt besitze.

Ich verlasse mich nicht gerne auf ein externes Dokument, damit jemand den Code versteht. Ja, es kann manchmal notwendig sein, besonders wenn es um arkane Details geht. Aber wenn immer möglich, versuche ich, alles im Code selbst zu belassen, damit er auf dem neuesten Stand bleibt und leicht zu finden ist. In diesem Fall schätze ich die Zugänglichkeit zu Informationen über die Aussagekraft der Dokumentation.

In unseren Projekten, die sich mit quantitativer Finanzökonomie befassen, verwenden wir eine Menge Mathematik und folgen einer Kombination aus dem, was bereits veröffentlicht wurde:

1. Stellen Sie einen Link zu der von Ihnen verwendeten Hauptquelle bereit. Am einfachsten geht das mit dem BibTex-Handle, einem Ausweis für ein Dokument, der von allen Beteiligten eingesehen werden kann. Abhängig von der spezifischen Quelle fügen wir regelmäßig die Gleichungsreferenz hinzu.

2. Geben Sie Erklärungen für alle Variablen an. Auch hier verwenden wir Tex, wenn auf dem Originalpapier Griechisch oder andere Buchstaben verwendet werden. Der Grund dafür ist, dass oft genug Papiere und Bücher unterschiedliche Bezeichnungen verwenden. Wenn jemand die Mathematik überarbeiten muss, ist dies viel einfacher.

3. Versuchen Sie, die Gleichung in einem Stück zu codieren. Auf diese Weise ist es viel einfacher zu erkennen. Veröffentlichen Sie den Tex-Code der vollständigen Gleichung NICHT im Code - entweder ist die Gleichung sehr kurz, und das Veröffentlichen von Texten ist unübersichtlich und überflüssig, oder die Gleichung ist riesig und der Tex-Code ist nutzlos, es sei denn, Sie kompilieren ihn (Verwenden Sie a Referenz statt). Das Zerlegen einer Gleichung in kleine Teile macht es wirklich schwierig zu verstehen, was vor sich geht (wenn Sie mindestens gut in Mathe sind).

Meiner Meinung nach ist die wichtigste Erkenntnis, dass Formeln oft vom Kontext abhängen. Jede mir bekannte mathematische Arbeit nimmt sich Zeit, um die Umgebung des Modells einzurichten. Do solltest das auch machen.

Text hat nicht die Ausdruckskraft von Mathematik

Du hast recht. Da Sie bereits nach einer Möglichkeit suchen, dies außerhalb von Code zu tun, und Tex neben einer steilen Lernkurve ein Übermaß darstellt, lautet meine Empfehlung wie folgt:

Verwenden Sie den OpenOffice.org/LibreOffice Math Equation Editor.

Es ist kostenlos. Es ist offen.

Sie können es entweder visuell verwenden oder Sie können die Gleichungen in einer speziellen Sprache schreiben.

Sie müssen die Sprache nicht sofort lernen, da bei Verwendung der GUI der "Code" in einem Bedienfeld generiert wird, damit Sie ihn sehen können.

Im oberen Bereich können Sie die Gleichungen mit einer Palette "zeichnen". Im unteren Bereich wird die entsprechende Notation generiert. Sie können es auch umgekehrt machen, wenn Sie die Notation verstanden haben, im unteren Bereich in Notation schreiben und die grafische Ausgabe im oberen Bereich sehen.