Dokumentation der mathematischen Logik im Code

19

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.

jmruc
quelle
5
TeX zu lernen ist eigentlich gar nicht so schwer. Wenn Sie Ihren Code irgendwo online haben, druckt MathJax ihn in kürzester Zeit hübsch aus. Denken Sie bitte daran, dass es Sprachen wie HAL / S gibt, in denen Ihre Bedenken vor langer Zeit aufgegriffen wurden.
Deer Hunter
4
Ich möchte nicht mein eigenes Horn betätigen , aber hier ist ein Beispiel: meta.stackexchange.com/a/49787/141513 Die Idee ist, es so zu schreiben, dass jemand, der es sich ansieht, verstehen kann, was es tut, auch wenn er es nicht versteht die Mathematik dahinter. Gute Funktions- / Variablennamen und ein oder zwei einfache Kommentare reichen normalerweise aus, um dies zu tun.
BlueRaja - Danny Pflughoeft

Antworten:

32

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.)

Kilian Foth
quelle
4
@ JustinC Nein, ich denke, er meint die gleichen Variablennamen, dh wenn es heißt, dass y = m*x + cSie m, x und c als Variablen verwenden
jk.
5
@ JustinC Ich meinte: Verwenden Sie nur die Variablen- und Konstantennamen, die in der Publikation enthalten sind - normalerweise sind dies Ein-Buchstaben-Namen wie n, f, q oder vielleicht n_i. Ich stimme dem OP zu, EulerLinearMomentumdas dann tatsächlich weniger lesbar ist m. Der Punkt ist, dass der Quellcode nicht das bevorzugte Medium zum Ausdrücken von Formeln ist, daher sollte der Schwerpunkt darauf liegen, zu überprüfen, dass der Code das Gleiche wie die gedruckte Formel tut und nicht, dass der Code die Programmanforderungen erfüllt.
Kilian Foth
1
Ich würde dieser Strategie zustimmen. Bei dem Text, über den wir sprechen, handelt es sich jedoch um Code, dem Einschränkungen zugrunde liegen, einschließlich einer bestimmten Genauigkeit / Skalierung und eines bestimmten Verhaltens (bei einem bekannten Host oder Ziel). Sie spezifizieren oder entwerfen kein mathematisches Modell, sondern implementieren es (in den meisten Fällen) in Code. Ohne Verwendung von Eigennamen , die beschreiben, was dargestellt wird, ist es viel schwieriger, die Absicht zu überprüfen.
JustinC
2
+1. Wenn sich der Verweis auf eine kürzlich erschienene Veröffentlichung bezieht, geben Sie den DOI-Hyperlink zum Artikel an. Beispiel dx.doi.org/10.1000/182 . Genau dafür wurde DOI entwickelt - eine kurze, standardmäßige URL für eine Publikation, die garantiert nie geändert wird.
MarkJ
2
Bei einer kleinen Gleichung, bei der jede Variable eine physikalische Bedeutung hat, hängt @KeithS völlig davon ab, aber was ist, wenn Sie einen FFT-Algorithmus implementieren, bei dem es mehrere Teilergebnisse ohne physikalische Bedeutung gibt. In dieser Situation sollten Sie unbedingt mit der mathematischen Literatur übereinstimmen, da es sich um die Domänensprache handelt
jk.
8

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.


quelle
6

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.

zuiqo
quelle
1
Es ist eine großartige Idee, den Kontext im Detail zu erklären und sich auf das Warum zu konzentrieren, bevor das Wie wirklich hilfreich sein kann.
Jmruc
3

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.

Bildbeschreibung hier eingeben

Tulains Córdova
quelle
Dann was? Fügen Sie den Klartextcode für die Mathematiknotation als Kommentar in den Originalcode ein, oder machen Sie einen Screenshot und verwenden Sie Javadoc, wie es das OP mit TeX versprochen hat?
dodgethesteamroller
@dodgethesteamroller Ja, meine Antwort lautet "Da Sie bereits nach einer Möglichkeit suchen, dies außerhalb von Code zu tun, und Tex ist ein Overkill."
Tulains Córdova