L'obiettivo di questo tipo di specifica è quello di aiutare i lavoratori in entrata a tuffarsi nel codice. Deve inoltre aiutare i lavoratori sperimentati a mantenere una visione chiara del progetto.
Puoi cambiare il tuo progetto per un diagramma UML, in particolare un diagramma di attività nel tuo caso. Questo offre un modo (più o meno) standardizzato di rappresentare visivamente il tuo flusso di lavoro. Mostra le azioni eseguite nell'algoritmo, le scelte fatte, le opzioni disponibili per ogni scelta, i loop, ecc. Puoi anche mostrare l'inizio e la fine del tuo processo, mostrare gli elementi richiesti o prodotti da esso, ed evidenziare alcuni punti grazie ai commenti.
Ad un livello più basso, commentare in modo intelligente il codice è sempre una buona idea. Generalmente, si deve specificare, per ogni pezzo di codice (funzione, metodo, classe, ...)
- I suoi input e quali proprietà devono rispettare (l'elenco deve essere ordinato, ecc.);
- Il suo output;
- Cosa succede in casi particolari (una lista vuota, un input non valido, ecc.). Indica le eccezioni suscettibili, se la tua lingua le supporta;
- I suoi effetti collaterali (idealmente non dovrebbe avere nessuno). In genere la lettura / scrittura da / a file, rete, ecc.;
- Se è thread-safe. Cioè, se il suo stato può essere cambiato durante l'esecuzione da parte di un'entità esterna. Verifica ad esempio se l'elenco fornito come input può essere modificato esternamente. La sicurezza del filo è molto importante in un ambiente multi-thread, ovviamente, ma anche questo è un segnale di qualità. Gli sviluppatori dovrebbero stare molto attenti quando usano un pezzo di codice non sicuro.
- Il consumo di tempo e di memoria, con i suoi input. Gli utenti esterni vogliono risposte a domande del tipo "Posso fornire una (molto) grande lista a questa funzione senza problemi di calcolo del tempo?".
- Il contesto in cui deve essere usato, se questo contesto può influenzare il suo comportamento (idealmente non dovrebbe essere il caso dato che gli unici fattori che influenzano dovrebbero essere i suoi input).
- Se richiesto, come crearlo e testarlo automaticamente.
Utilizza strumenti che ti consentono di aggiungere tali commenti nel codice e di generare automaticamente rapporti in un documento separato. Vedi javadoc o doxygen per esempio. Grazie a questi strumenti, è possibile aggiornare le informazioni nello stesso momento in cui si modifica il codice e ottenere una documentazione separata sempre aggiornata.
Completa le specifiche con test automatici e considerali come parte della documentazione. I test descrivono quale dovrebbe essere il comportamento del codice in situazioni normali e in situazioni eccezionali.
Il tuo motore dovrebbe quindi essere considerato come una raccolta di entità che comunicano insieme. Sai come funziona ogni entità, come le entità devono agire insieme e come agiscono in situazioni rappresentative.
Nota che questa non è una difesa di OOP, dal momento che le "entità" possono essere funzioni (in programmazione funzionale), strutture, classi (in OOP), ecc.