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.