Come posso documentare strutture di codice necessariamente complesse?

Se ho un pezzo di codice che è matematicamente o strutturalmente piuttosto complesso e irriducibilmente così, come potrei fare per documentare questo pezzo di codice? In particolare, come posso garantire che qualcuno che non abbia le capacità matematiche o architettoniche che posso fare possa capirlo dalla documentazione? Devo documentare anche tutta la matematica? Link a un tutorial? Qualche collegamento di aiuto visivo nel caso di strutture complesse?

Questo dipende davvero da quanto sia complicato il codice e la matematica. Il codice stesso dovrebbe - come sempre - essere il più autocompattante possibile. Denominare le variabili correttamente, implementare metodi logici e concisi (piuttosto che mega-funzioni), eventualmente aggiungere la documentazione in linea (cioè quando non è ovvio cosa stia effettivamente facendo il codice).

Se stai usando un algoritmo non ovvio, aggiungi un link a un riferimento alla fonte. Questa è una pratica ragionevole perché offre allo sviluppatore un modo molto rapido per scoprire cosa stai facendo. Come ho detto, questo è utile se si tratta di un algoritmo non ovvio ma complesso. Ciò dovrebbe dimostrare che (a) stai facendo qualcosa di sensato e (b) qualcuno ha dimostrato che funziona.

Un buon esempio è il lavoro svolto sulla corrispondenza del testo sfocato. Ho fatto una ricerca sostanziale sugli algoritmi e implementato quello che è noto come "algoritmo di Smith-Waterman" (che viene effettivamente utilizzato per le sequenze di DNA, ma si applica in generale al "matching"). Quindi, invece di implementare semplicemente l'algoritmo, ho trovato riferimenti online e ho incluso un collegamento o due. Come sopra, questo dimostra che (a) il mio algoritmo corrisponde all'algoritmo pubblicato, e (b) l'algoritmo è stato rivisto e dimostrato di funzionare.

Tuttavia, ciò non spiega necessariamente come funziona il codice e cosa dovrebbero fare le varie classi. Quando vai a scrivere della documentazione "reale", una guida per sviluppatori al sistema, dovresti spiegare cosa hai fatto e fornire informazioni sufficienti per il supporto futuro. Secondo me questo documento dovrebbe essere leggibile da una persona tecnicamente agnostica; non ha bisogno di essere "stupito", ma dovrebbe escludere il gergo e non fare affidamento sulla conoscenza presunta.

I commenti sulla fonte sono la prima cosa da fare. Questo assicura che ci sia un collegamento diretto alla documentazione direttamente dal codice. Se la documentazione è molto complicata, considera di pubblicare solo un abstract nei commenti, quindi un link ad un documento esterno che contiene una descrizione più completa dell'architettura / algoritmo complesso. Se non è troppo complicato, tuttavia, considera di includere tutta la documentazione in un unico posto. Ciò massimizzerà la probabilità che il codice / la documentazione rimangano sincronizzati e vengano letti insieme.

Documenta il codice nella misura in cui il tuo team / azienda ne ha bisogno. Se un jr. dev sarà tenuto a mantenere il codice, potrebbe essere necessario entrare nei dettagli su alcuni aspetti matematici. Questa è una decisione di gestione e devono darti il ​​tempo necessario.

Non credo che tu debba documentare il codice così tanto da rendere conto di essere sostituito da uno sviluppatore minore. Se questo è un problema, devi avere il tempo di documentare.

Non dovresti fare la ricerca sul web per loro.