Se ho un pezzo di codice che è matematicamente o strutturalmente abbastanza complesso e irriducibilmente così, come farei per documentare questo pezzo di codice? In particolare, come posso garantire che qualcuno che non possiede le abilità matematiche o architettoniche che conosco possa capirlo dalla documentazione? Dovrei documentare anche tutta la matematica? Link ad un tutorial? Fare qualche collegamento visivo di aiuto nel caso di strutture complesse?
Questo dipende davvero dalla complessità del codice e della matematica. Il codice stesso dovrebbe - come sempre - essere il più auto-documentabile possibile. Assegna nomi alle variabili correttamente, implementa metodi logici e concisi (piuttosto che mega-funzioni), aggiungi la documentazione in linea dove appropriato (ad esempio quando non è evidente ciò che il codice sta effettivamente facendo).
Se stai utilizzando un algoritmo non ovvio, aggiungi un link a un riferimento alla fonte. Questa è una pratica ragionevole perché offre allo sviluppatore un modo molto veloce 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 che ha senso, e (b) qualcuno ha dimostrato che funziona.
Un buon esempio è un po 'di lavoro che ho fatto intorno alla corrispondenza del testo fuzzy. Ho fatto ricerche approfondite sugli algoritmi e ho implementato quello che è noto come "algoritmo di Smith-Waterman" (che è effettivamente usato per le sequenze di DNA, ma si applica generalmente al "matching"). Quindi, invece di implementare semplicemente l'algoritmo, ho trovato i riferimenti online e incluso un link o due. Come sopra, questo dimostra che (a) il mio algoritmo corrisponde all'algoritmo pubblicato e (b) l'algoritmo è stato rivisto e mostrato come funzionante.
Tuttavia questo non spiega necessariamente come funziona il codice e cosa dovrebbero fare le varie classi. Quando vai a scrivere una "vera" documentazione - una guida per sviluppatori al sistema - dovresti spiegare cosa hai fatto e fornire informazioni sufficienti per il supporto futuro. A mio parere questo documento dovrebbe essere leggibile da una persona tecnicamente agnostica; non ha bisogno di essere "snobbato", ma dovrebbe escludere il gergo e non fare affidamento sulla presunta conoscenza.
I commenti che circondano la fonte sono la prima cosa che dovresti fare. Ciò assicura che vi sia un collegamento diretto alla documentazione direttamente dal codice. Se la documentazione è molto complicata, considera di postare solo un abstract nei commenti e quindi un link ad un documento esterno che contenga una descrizione più completa dell'architettura / algoritmo complesso. Se non è troppo complicato, tuttavia, considera di includere tutta la documentazione in un unico posto. Ciò consentirà di massimizzare la probabilità che il codice / la documentazione rimangano sincronizzati e vengano letti insieme.
Documenta il codice nella misura in cui il tuo team / azienda ha bisogno. Se un jr. dev sarà necessario per mantenere il codice, potrebbe essere necessario entrare nei dettagli di alcuni dei calcoli matematici. Questa è una decisione di gestione e devono darti il tempo necessario.
Non penso 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.
Leggi altre domande sui tag documentation