Dokumentowanie logiki matematycznej w kodzie

19

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.

jmruc
źródło
5
Nauka TeXa nie jest tak trudna. Jeśli masz gdziekolwiek swój kod online, MathJax wydrukuje go w pół sekundy. Pamiętaj, że istnieją takie języki, jak HAL / S, w których twoje obawy zostały wyrażone dawno temu.
Deer Hunter
4
Nie trącić własnym rogiem, ale oto jeden przykład: meta.stackexchange.com/a/49787/141513 Chodzi o to, aby napisać go, aby ktoś, kto na niego patrzy, mógł zrozumieć, co robi, nawet jeśli nie rozumie matematyka za tym. Zazwyczaj wystarczają do tego dobre nazwy funkcji / zmiennych oraz prosty komentarz lub dwa.
BlueRaja - Danny Pflughoeft
patrz także: „Komentarze to zapach kodu”
komik

Odpowiedzi:

32

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

Kilian Foth
źródło
4
@ JustinC nie Myślę, że on ma na myśli te same nazwy zmiennych, tzn. Jeśli mówi, y = m*x + cże używasz m, x ic jako zmiennych
jk.
5
@JustinC Miałem na myśli: używaj tylko tych zmiennych i nazw stałych, które są w publikacji - zwykle są to nazwy jednoliterowe, takie jak n, f, q lub może n_i. Zgadzam się z OP, który EulerLinearMomentumjest wtedy mniej czytelny m. Chodzi o to, że kod źródłowy nie jest preferowanym medium do wyrażania formuł, dlatego należy położyć nacisk na ułatwienie sprawdzenia, czy kod działa tak samo jak drukowana formuła, a nie, czy kod spełnia wymagania programu.
Kilian Foth
1
Zgodziłbym się z tą strategią; jednak tekst, o którym mówimy, to kod, którego kod ma podstawowe ograniczenia, w tym określoną precyzję / skalę i zachowanie (w przypadku znanego hosta lub celu). Nie określasz ani nie projektujesz modelu matematycznego, implementujesz go w kodzie (w większości przypadków). Bez używania prawidłowych nazw opisujących to, co jest reprezentowane, znacznie trudniej jest zweryfikować zamiar.
JustinC
2
+1. Jeśli odwołanie dotyczy najnowszej publikacji, podaj do dokumentu hiperłącze DOI . Przykład dx.doi.org/10.1000/182 . Właśnie do tego został zaprojektowany DOI - krótki, standardowy adres URL publikacji, który nigdy się nie zmieni.
MarkJ
2
@KeithS całkowicie zależy od małego równania, w którym każda zmienna ma znaczenie fizyczne, ale co jeśli wdrażasz powiedz algorytm FFT, w którym będzie kilka wyników cząstkowych bez fizycznego znaczenia. W takiej sytuacji absolutnie powinieneś dopasować literaturę matematyczną, ponieważ jest to język domen
jk.
8

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.


źródło
6

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.

zuiqo
źródło
1
Szczegółowe wyjaśnienie kontekstu to świetny pomysł, skupienie się na „dlaczego” przed „jak” może być naprawdę pomocne.
jmruc
3

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.

wprowadź opis zdjęcia tutaj

Tulains Córdova
źródło
Co wtedy Czy dołączyć komentarz tekstowy do notacji matematycznej w oryginalnym kodzie jako komentarz, czy zrobić zrzut ekranu i użyć Javadoc tak, jak OP powiedział, że mógłby zrobić z TeX-em?
dodgethesteamroller
@dodgethesteamroller Tak, moja odpowiedź mówi: „Skoro już szukasz sposobu na zrobienie tego poza kodem, a Tex to przesada…”
Tulains Córdova