Dokumentowanie logiki matematycznej w kodzie

Czasami, choć nie często, muszę zawrzeć logikę matematyczną w kodzie. Stosowane pojęcia są w większości bardzo proste, ale wynikowy kod nie jest - wiele zmiennych o niejasnym celu i niektóre operacje o mniej oczywistych zamiarach. Nie oznacza to, że kod jest nieczytelny lub unmaintainable, tylko że to waaaay trudniejszy do zrozumienia niż rzeczywisty problem matematyczny. Staram się komentować te fragmenty, które są najtrudniejsze do zrozumienia, ale jest taki sam problem, jak po prostu ich kodowanie - tekst nie ma ekspresyjnej mocy matematyki .

Szukam bardziej wydajnego i łatwego do zrozumienia sposobu wyjaśnienia logiki stojącej za złożonym kodem, najlepiej w samym kodzie. Rozważyłem TeXa - pisanie dokumentacji i generowanie jej oddzielnie od kodu. Ale wtedy musiałbym nauczyć się TeXa, a dokumentacja nie będzie w samym kodzie. Inną rzeczą, o której myślałem, było zrobienie zdjęcia zapisów matematycznych, równań i diagramów zapisanych na papierze / tablicy, a także włączenie go do javadoc.

Czy istnieje prostszy i jaśniejszy sposób?

PS Nadanie zmiennym nazw opisowych ( timeOfFirstEventzamiast t1) powoduje, że kod jest bardziej szczegółowy, a nawet trudniejszy do odczytania.

Właściwą rzeczą do zrobienia w takich okolicznościach jest wdrożenie algorytmu, formuły lub czegokolwiek o dokładnie takich samych nazwach zmiennych, jak w podstawowym źródle świata rzeczywistego (o ile pozwala na to język programowania), i zwięzły komentarz powyżej coś takiego jak „Obliczanie odległości Levenshteina zgodnie z opisem w [Knuth1968]”, gdzie cytat łączy się z łatwo dostępnym opisem matematyki.

(Jeśli nie masz takiego odniesienia, ale twoja matematyka jest solidna i przydatna, może powinieneś rozważyć opublikowanie go samodzielnie. Po prostu powiedz.)

Kiedy musiałem zaimplementować takie algorytmy, robię kilka rzeczy.

1. W miarę możliwości izoluj algorytm do jego własnej metody lub najlepiej klasy. Mój obecny projekt ma własną Mathklasę równoważną do dodawania złożonych algorytmów.

2. Podaj podsumowanie tego, co algorytm powinien robić w kategoriach „świeckich”, w tym wszelkie popularne akronimy lub skróty do tego terminu. Robię to w samej metodzie, więc żyje z kodem.

3. Podaj streszczenie algorytmu pod względem technicznym / matematycznym i dołącz wszelkie odniesienia zewnętrzne, które znam. Ponownie robię to z samą metodą, aby miała większą szansę na pozostanie aktualna. Zwykły tekst nie jest w tym przypadku świetny, więc zacytuję matematyczny termin najlepiej jak potrafię i wyjaśnię go w nawiasowym komentarzu obok niego. Na przykład, x^y (x raised to the power y)

4. Udokumentuj, w jaki sposób dzielę algorytm na komponenty i wskaż, co każda zmienna reprezentuje w algorytmie. na przykład.t1 is time of first event

5. Koduj algorytm i komentuj złożone części. Zasadniczo dodam komentarz gdziekolwiek zrobię krok, który nie byłby oczywisty ani prosty w obrębie samego algorytmu. W szczególności upewniam się, że komentuję wszelkie nieoczywiste skróty i dlaczego są one w porządku, że mogę je zastosować w ramach wdrożenia.

6. Napisz kilka testów jednostkowych, które potwierdzą działanie algorytmu.

Wreszcie, jeśli jest to naprawdę, bardzo, bardzo skomplikowane, to pogodzę się z faktem, że jestem właścicielem tego kodu do końca mojego projektu.

Nie lubię polegać na zewnętrznym dokumencie, aby ktoś inny zrozumiał kod. Tak, czasem może być to konieczne, szczególnie gdy zagłębia się w tajemnicze szczegóły. Ale gdy tylko jest to możliwe, staram się zachować wszystko w samym kodzie, aby miał szansę na aktualizację i łatwą lokalizację. W tym przypadku cenię dostępność informacji zamiast wyrazistości dokumentacji.

W naszych projektach, które obracają się wokół badań w zakresie ilościowej ekonomii finansowej, wykorzystujemy DUŻO matematyki i postępujemy zgodnie z kombinacją tego, co już zostało opublikowane:

1. Podaj link do głównego źródła, którego używasz. Dla nas najłatwiejszym sposobem na to jest użycie uchwytu BibTex, który jest w zasadzie identyfikatorem dokumentu, który może sprawdzić wszyscy. W zależności od konkretnego źródła regularnie dodajemy również odniesienia do równania.

2. Podaj wyjaśnienia dla wszystkich zmiennych. Ponownie używamy do tego Tex, jeśli oryginalny papier używa greckich lub innych liter. Powodem tego jest to, że często wystarczająca liczba dokumentów i książek używa różnych zapisów. Jeśli ktoś musi przerobić matematykę, to znacznie ułatwia.

3. Spróbuj zakodować równanie w jednym kawałku. W ten sposób łatwiej jest rozpoznać. NIE publikuj w kodzie kodu Tex pełnego równania - albo równanie jest bardzo krótkie, a wysyłanie tex jest nieporządne i zbędne, lub równanie jest ogromne, a kod tex jest bezużyteczny, chyba że go skompilujesz (użyj odniesienie zamiast). Rozłożenie równania na małe kawałki sprawia, że ​​naprawdę trudno jest zrozumieć, co się dzieje (jeśli przynajmniej jesteś dobry z matematyki).

IMHO, najważniejszą realizacją jest to, że formuły często zależą od kontekstu. Każdy papier matematyczny, który znam, zajmuje trochę czasu, aby skonfigurować środowisko modelu; Powinieneś zrobić to samo.

tekst nie ma ekspresyjnej mocy matematyki

Masz rację. Ponieważ już szukasz sposobu na zrobienie tego poza kodem, a Tex to przesada poza tym, że ma stromą krzywą uczenia się, dlatego zalecam:

Użyj OpenOffice.org/LibreOffice Math Equation Editor.

Jest wolne. Jest otwarte.

Możesz używać go wizualnie lub pisać równania w specjalnym języku.

Nie musisz od razu uczyć się języka, ponieważ podczas korzystania z GUI „kod” jest generowany w panelu, abyś mógł go zobaczyć.

W górnym panelu możesz „rysować” równania za pomocą palety. W dolnym panelu generowana jest równoważna notacja. Możesz to zrobić na odwrót, gdy tylko zrozumiesz notację, pisząc notację w dolnym panelu i widząc wynik graficzny w górnym panelu.