Documentare la logica matematica nel codice

La cosa giusta da fare in tali circostanze è implementare l'algoritmo, la formula o qualsiasi altra cosa con esattamente gli stessi nomi delle variabili della fonte primaria reale (per quanto il linguaggio di programmazione lo consenta ), e hanno un breve commento sopra di esso dicendo qualcosa come "Calcolo della distanza di Levenshtein come descritto in [Knuth1968]", dove la citazione si collega a una descrizione facilmente accessibile della matematica.

(Se non hai hai tale riferimento, ma la tua matematica è valida e utile, forse dovresti prendere in considerazione la possibilità di pubblicarla tu stesso. Basta dire '.)

Quando ho dovuto implementare algoritmi del genere, ci sono un paio di cose che faccio.

1. Per quanto possibile, isolare l'algoritmo con il proprio metodo o preferibilmente classe. Il mio progetto attuale ha la sua classe Math equivalente per aggiungere algoritmi complessi a

2. Fornire un riepilogo di ciò che l'algoritmo dovrebbe fare in termini di disposizione, compresi eventuali acronimi comuni o riferimenti sintetici al termine. Lo faccio nel metodo stesso, quindi vive con il codice.

3. Fornire un riepilogo dell'algoritmo in termini tecnici / matematici e includere eventuali riferimenti esterni che io conosca. Ancora una volta, lo faccio con il metodo stesso, quindi ha una migliore possibilità di rimanere pertinenti. In questo caso, il testo semplice non è eccezionale, quindi citerò il termine matematico come meglio posso e chiarirò in un commento parentetico accanto ad esso. Ad esempio, x^y (x raised to the power y)

4. Documenta in che modo suddivido l'algoritmo in componenti e indico ciò che ciascuna variabile rappresenta nell'algoritmo. per esempio. t1 is time of first event

5. Codifica l'algoritmo e commenta le parti complesse. In sostanza, aggiungerò un commento ovunque io compia un passo che non era ovvio o diretto all'interno dell'algoritmo stesso. In particolare, mi assicuro di commentare qualsiasi scorciatoia non ovvia e perché sono a posto che posso occuparmi dell'implementazione.

6. Scrivi alcuni test unitari che valideranno il funzionamento dell'algoritmo.

Infine, se è davvero, davvero, davvero complesso, mi rassegno al fatto che posseggo quel codice per il resto del mio tempo su quel progetto.

Non mi piace affidarsi a un documento esterno perché qualcun altro possa capire il codice. Sì, a volte può essere necessario soprattutto quando si entrano in dettagli arcani. Ma quando possibile, cerco di mantenere tutto all'interno del codice stesso in modo che abbia una possibilità di rimanere aggiornato e facilmente individuabile. In questo caso, apprezzo l'accessibilità alle informazioni rispetto all'espressività della documentazione.

Nei nostri progetti, che ruotano intorno alla ricerca in economia finanziaria quantitativa, utilizziamo un sacco di matematica, e seguiamo una combinazione di ciò che è già stato pubblicato:

1. Fornisci un link alla fonte principale che stai utilizzando. Per noi, il modo più semplice per farlo è utilizzare l'handle BibTex, che è fondamentalmente un ID per un documento che può essere consultato da tutti gli interessati. A seconda della fonte specifica, aggiungiamo regolarmente anche il riferimento all'equazione.

2. Fornisci spiegazioni per tutte le variabili. Ancora una volta, usiamo Tex per questo se la carta originale utilizza lettere greche o di altro tipo. La ragione di ciò è che spesso giornali e libri usano notazioni diverse. Se qualcuno ha bisogno di rielaborare i calcoli matematici, questo lo rende molto più semplice.

3. Tentativo di codificare l'equazione in un unico pezzo. È molto più facile riconoscere in questo modo. NON inserire il codice Tex dell'equazione completa nel codice - l'equazione è molto breve, e l'inserimento di tex è disordinato e superfluo, o l'equazione è enorme, e il codice tex è inutile, a meno che non lo compili (usa un riferimento invece). Disassemblare un'equazione in piccoli pezzi rende davvero difficile capire cosa sta succedendo (se sei bravo in matematica almeno).

IMHO, la realizzazione più importante è che le formule dipendono spesso dal contesto. Ogni carta matematica che conosco prende tempo per impostare l'ambiente del modello; Dovresti fare lo stesso.

text does not have the expressive power of math

Hai ragione. Dal momento che stai già cercando un modo per farlo fuori codice, e Tex è un overkill oltre ad avere una curva di apprendimento ripida, la mia raccomandazione è la seguente:

Utilizza OpenOffice.org/LibreOffice Math Equation Editor.

È gratuito. È aperto.

Puoi usarlo visivamente oppure puoi scrivere le equazioni in una lingua speciale.

Non devi imparare subito la lingua perché quando usi la GUI, il "codice" viene generato in un pannello che puoi vedere.

Nel pannello superiore puoi "disegnare" le equazioni usando un pallete. Nel pannello inferiore viene generata la notazione equivalente. Puoi farlo viceversa una volta che hai compreso la notazione, scrivendo nella notazione nel pannello inferiore e vedendo l'output grafico nel pannello superiore.