Documentare la logica matematica nel codice

A volte, anche se non spesso, devo includere la logica matematica nel mio codice. I concetti utilizzati sono per lo più molto semplici, ma il codice risultante non lo è: molte variabili con scopi poco chiari e alcune operazioni con intenzioni non così ovvie. Non intendo dire che il codice sia illeggibile o non mantenibile , ma solo che è molto più difficile da capire rispetto al vero problema di matematica. Cerco di commentare le parti che sono più difficili da capire, ma c'è lo stesso problema del solo codificarle: il testo non ha il potere espressivo della matematica .

Sto cercando un modo più efficiente e di facile comprensione per spiegare la logica dietro alcuni dei codici complessi, preferibilmente nel codice stesso. Ho considerato TeX: scrivere la documentazione e generarla separatamente dal codice. Ma poi dovrei imparare TeX e la documentazione non sarà nel codice stesso. Un'altra cosa a cui ho pensato è scattare una foto delle notazioni matematiche, delle equazioni e dei diagrammi scritti su carta / lavagna e includerla in javadoc.

C'è un modo più semplice e chiaro?

PS Assegnare nomi descrittivi ( timeOfFirstEventanziché t1) alle variabili rende il codice più dettagliato e persino più difficile da leggere.

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

(Se non hai un riferimento del genere, ma la tua matematica è solida e utile, forse dovresti prendere in considerazione la pubblicazione da solo. Dì semplicemente.)

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 una sua Mathclasse equivalente a cui aggiungere algoritmi complessi.

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

3. Fornire un riepilogo dell'algoritmo in termini tecnico / matematici e includere eventuali riferimenti esterni che conosco. Ancora una volta, lo faccio con il metodo stesso, quindi ha maggiori possibilità di rimanere rilevante. Il semplice testo in questo caso non è eccezionale, quindi citerò il termine matematico come meglio posso e chiarirò in un commento tra parentesi accanto ad esso. Per esempio, x^y (x raised to the power y)

4. Documenta come sto dividendo l'algoritmo in componenti e indica cosa rappresenta ogni variabile 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 faccia un passo che non era ovvio o semplice all'interno dell'algoritmo stesso. In particolare, mi assicuro di commentare eventuali scorciatoie non ovvie e il motivo per cui vanno bene che io possa prendere all'interno dell'implementazione.

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

Alla fine, se è davvero molto complesso, allora mi rassegno al fatto di possedere quel codice per il resto del mio tempo in quel progetto.

Non mi piace fare affidamento su un documento esterno affinché qualcun altro comprenda il codice. Sì, a volte può essere necessario soprattutto quando si entra in dettagli arcani. Ma quando possibile, cerco di mantenere tutto all'interno del codice stesso in modo che abbia la possibilità di rimanere aggiornato e facilmente individuabile. In questo caso, apprezzo l'accessibilità alle informazioni sull'espressività della documentazione.

Nei nostri progetti, che ruotano attorno alla ricerca in economia finanziaria quantitativa, utilizziamo MOLTA 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 è usare la maniglia BibTex, che è fondamentalmente un ID per un documento che può essere consultato da tutti i soggetti coinvolti. A seconda della fonte specifica, aggiungiamo regolarmente anche il riferimento all'equazione.

2. Fornire spiegazioni per tutte le variabili. Ancora una volta, usiamo Tex per questo se il documento originale usa lettere greche o di altro tipo. La ragione di ciò è che spesso abbastanza carte e libri usano notazioni diverse. Se qualcuno ha bisogno di rielaborare la matematica, questo rende molto più semplice.

3. Tentativo di codificare l'equazione in un unico pezzo. È molto più facile riconoscerlo in quel modo. NON inserire nel codice il codice Tex dell'equazione completa - o l'equazione è molto breve e la pubblicazione di tex è disordinata e superflua, oppure 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 almeno sei bravo in matematica).

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

il testo non ha il potere espressivo della matematica

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

Utilizzare l'Editor equazione matematica OpenOffice.org/LibreOffice.

È gratis. È aperto.

Puoi usarlo sia visivamente o 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 per essere visto.

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