Wie dokumentiere ich notwendigerweise komplexe Codestrukturen?

Wenn ich einen Code habe, der mathematisch oder strukturell recht komplex und irreduzibel ist, wie würde ich diesen Code dokumentieren? Wie kann ich insbesondere sicherstellen, dass jemand, der möglicherweise nicht über die mathematischen oder architektonischen Fähigkeiten verfügt, die ich habe, dies anhand der Dokumentation verstehen kann? Soll ich auch die ganze Mathematik dokumentieren? Link zu einem Tutorial? Verknüpfung mit visuellen Hilfsmitteln bei komplexen Strukturen?

Dies hängt wirklich davon ab, wie kompliziert der Code und die Mathematik sind. Der Code selbst sollte - wie immer - so selbstdokumentierend wie möglich sein. Benennen Sie Variablen korrekt, implementieren Sie logische und präzise Methoden (anstelle von Megafunktionen) und fügen Sie gegebenenfalls eine Inline-Dokumentation hinzu (dh wenn nicht klar ist, was der Code tatsächlich tut).

Wenn Sie einen nicht offensichtlichen Algorithmus verwenden, fügen Sie einen Link zu einer Referenz hinzu, die die Quelle ist. Dies ist eine vernünftige Vorgehensweise, da der Entwickler auf diese Weise sehr schnell herausfinden kann, was Sie tun. Wie gesagt, dies ist nützlich, wenn es sich um einen nicht offensichtlichen, aber komplexen Algorithmus handelt. Dies sollte beweisen, dass (a) Sie etwas tun, das Sinn macht, und (b) jemand gezeigt hat, dass es funktioniert.

Ein gutes Beispiel ist eine Arbeit, die ich zum Fuzzy-Text-Matching gemacht habe. Ich habe mich intensiv mit Algorithmen befasst und den sogenannten "Smith-Waterman-Algorithmus" implementiert (der eigentlich für DNA-Sequenzen verwendet wird, aber allgemein für "Matching" gilt). Anstatt den Algorithmus einfach zu implementieren, habe ich online Referenzen gefunden und ein oder zwei Links eingefügt. Wie oben zeigt dies, dass (a) mein Algorithmus mit dem veröffentlichten Algorithmus übereinstimmt und (b) der Algorithmus überprüft wurde und funktioniert.

Dies erklärt jedoch nicht unbedingt, wie der Code funktioniert und was die verschiedenen Klassen tun sollen. Wenn Sie eine "echte" Dokumentation schreiben - eine Entwickleranleitung für das System - sollten Sie erklären, was Sie getan haben, und genügend Informationen für die zukünftige Unterstützung bereitstellen. Meiner Meinung nach sollte dieses Dokument von einer technisch agnostischen Person gelesen werden können. es muss nicht "niedergeschlagen" werden, aber es sollte Jargon ausschließen und sich nicht auf angenommenes Wissen verlassen.

Kommentare rund um die Quelle sind das erste, was Sie tun sollten. Dies stellt sicher, dass direkt neben dem Code ein direkter Link zur Dokumentation besteht. Wenn die Dokumentation sehr kompliziert ist, sollten Sie nur eine Zusammenfassung in Kommentaren und dann einen Link zu einem externen Dokument veröffentlichen, das eine vollständigere Beschreibung der Architektur / des komplexen Algorithmus enthält. Wenn es jedoch nicht zu kompliziert ist, sollten Sie die gesamte Dokumentation an einem Ort zusammenfassen. Dies maximiert die Wahrscheinlichkeit, dass Ihr Code / Ihre Dokumentation synchron bleibt und zusammen gelesen wird.

Dokumentieren Sie den Code in dem Umfang, in dem Ihr Team / Unternehmen ihn benötigt. Wenn ein jr. dev wird benötigt, um den Code zu pflegen. Möglicherweise müssen Sie einige Details der Mathematik näher erläutern. Dies ist eine Managemententscheidung und sie müssen Ihnen die notwendige Zeit geben.

Ich denke nicht, dass Sie den Code so sehr dokumentieren müssen, dass Sie dafür verantwortlich sind, von einem geringeren Entwickler ersetzt zu werden. Wenn dies ein Problem darstellt, müssen Sie Zeit zum Dokumentieren haben.

Sie sollten nicht die Websuche nach ihnen durchführen müssen.