Ricerca di consigli sulla documentazione del sistema

5

Ho un motore di valutazione (è fondamentalmente un algoritmo) che quando ho iniziato non aveva documentazione formale. Abbiamo creato una specifica / scomposizione funzionale che è il nostro documento di livello aziendale, ma ora ho bisogno di qualcosa di più tecnico (una specifica tecnica).

Quello che sto cercando di capire è come si presenta quel documento, in che formato dovrebbe essere e in che livello di dettaglio dovremmo andare.

Stiamo commentando tutto il codice. Abbiamo anche un documento approssimativo chiamato Blueprint che riflette il flusso del modello ed è scritto in pseudo codice. La combinazione di questo modello e dei commenti del modello è sufficiente come specifica tecnica?

    
posta Shadders 30.10.2012 - 12:46
fonte

2 risposte

1

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.

    
risposta data 30.10.2012 - 14:51
fonte
0

Non scrivere commenti solo per il gusto di farlo. Commenta API pubblica, commenta l'espressione REGEX, commenta qualcosa di veramente difficile (raro trovare tutti i framework e gli strumenti disponibili). Non penso che questa sia una soluzione al tuo problema.

Scrivi un documento per una persona che non sa nulla di ciò che stai facendo. Il documento dovrebbe spiegare perché stai facendo questo, come lo stai facendo e come può essere testato (validato).

Trova qualcuno che non sappia nulla su cosa stai lavorando. Dagli il documento. Se ha perfettamente senso per loro, hai fatto un buon lavoro, altrimenti torna al tavolo da disegno.

    
risposta data 31.10.2012 - 01:01
fonte

Leggi altre domande sui tag