Documentazione di concetti di livello superiore

5

Lascerò il mio attuale progetto tra qualche giorno e, nel proteggere la mia conoscenza, mi è stato chiesto di aggiungere commenti al codice ovunque ritenga che possa aggiungere valore.

Il problema che sto incontrando ora è che i commenti che voglio scrivere non sono veramente adatti come commenti, perché non riguardano una singola entità nel codice (poche righe, una funzione, una classe o anche una file), ma si tratta più di come due o più entità interagiscono tra loro o di una funzionalità la cui implementazione è distribuita su più entità.

Quindi, come si fa a documentare cose che non appartengono a una singola entità ma è importante sapere per capire l'immagine più grande?

E anche: dove lo documentate? Nel file sorgente o in un documento esterno?

Ad esempio, abbiamo un'architettura client-server in C (con client e server entrambi in esecuzione sullo stesso dispositivo incorporato). Per evitare di sovraccaricare il server, il client ha un meccanismo per limitare l'invio di richieste simili al server in modo tale che una richiesta possa essere inviata solo se è stata data risposta alla precedente.

Le parti interne di questo meccanismo sono distribuite su più funzioni.

Dove posizioneresti la documentazione di tale funzione, specialmente se il file con la funzionalità ha anche altre funzioni non correlate?

Modifica : estese un po 'la domanda.

    
posta Bart van Ingen Schenau 14.12.2010 - 11:42
fonte

5 risposte

4

Probabilmente puoi utilizzare semplici diagrammi UML per evidenziare i concetti di alto livello.

    
risposta data 14.12.2010 - 12:06
fonte
2

Descrivi il sistema attraverso articoli tecnici che affrontano determinati scenari, descrivono modi di risoluzione dei problemi e così via.

Installa un wiki e inserisci gli articoli online in modo che gli altri membri del team possano modificarli in seguito.

    
risposta data 14.12.2010 - 11:47
fonte
1

Ho utilizzato TiddlyWiki per raccogliere alcune idee che non necessariamente renderebbero un testo coerente ... Questo ti dà un singolo File HTML che contiene un Wiki che chiunque può modificare.

Rispetto ad un vero Wiki, questo è molto più facile da configurare, e può essere memorizzato nell'albero dei sorgenti in modo che "segua" i rami e le modifiche tra di loro. D'altra parte, non è qualcosa che può essere modificato da più persone contemporaneamente.

    
risposta data 14.12.2010 - 12:25
fonte
1

+1 per Wiki.

Se si tratta di un sistema di trasmissione di messaggi, suggerisco di generare diagrammi di sequenza per mostrare l'interazione tra i diversi componenti. Ho usato il seguente sito Web per generare diagrammi dal testo semplice, quindi non c'è bisogno di smanettare con gli strumenti.

link

Una cosa che abbiamo trovato utile è chiedere alla persona che se ne va (in questo caso) di presentare un quiz relativo alla propria area di competenza e quindi fare una sessione separata per esaminare le domande e le risposte.

HTH

    
risposta data 20.12.2010 - 15:24
fonte
1

Suggerisco di mantenere intatto il codice e di descrivere il progetto in MS Word con riferimenti al codice sorgente e ai diagrammi UML di supporto. Non spendere sforzi su wiki - non hai né tempo né incentivi per una vera documentazione di riferimento. Il vero potere della wiki è la rete semantica costruita attorno ad alcuni argomenti e scrivere una wiki con una pagina è scadente.

Qualsiasi documentazione scritta dopo che il progetto è finito tende ad essere una dichiarazione ufficiale piuttosto che una giustificazione per sostenitore / manutentore. Questo è simile ai test delle unità di scrittura dopo l'implementazione del modulo. Anche se sono ancora utili ma sono molto meno dettagliate se scrivi prima i test.

Le decisioni di progettazione devono essere pronunciate prima di iniziare a implementare qualcosa. Potrebbe essere una semplice nota come "Ok ragazzi, ho un'idea, cosa ne pensate?" o proposta formale con diagrammi e riunioni UML. Ogni volta che inizio una nuova attività / componente, cerco di annunciare cosa esattamente farò. E il mezzo che scelgo non è molto importante - può essere e-mail, blog, wiki, JIRA ... Ovviamente il design cambierà in seguito, ma questi documenti serviranno come bozza per la documentazione di rilascio.

    
risposta data 11.02.2014 - 09:29
fonte

Leggi altre domande sui tag