Sto avviando una startup e io ei miei partner stiamo avendo problemi a tenerci aggiornati sul reciproco codice e su come implementare le loro funzioni. Il nostro codice è molto ben commentato, ma ognuno di noi ha scritto oltre 100 funzioni, e stiamo arrivando al punto in cui stiamo riscrivendo le funzioni che gli altri hanno scritto o utilizzando un modulo timer che qualcun altro sta usando per qualcos'altro.
Qual è la migliore pratica per documentare la C incorporata?
Come già sottolineato da altri, un'architettura può aiutare ad affrontare questo problema.
La tua implementazione è un'implementazione bare metal o hai un sistema operativo? Spiacente, non ho potuto chiedere nei commenti, perché il mio livello di reputazione è troppo basso. Se si tratta di un'implementazione bare metal, ho fatto delle buone esperienze con la seguente stratificazione per progetti di piccole dimensioni (ish) e di medie dimensioni:
La direzione di chiamata sarebbe:
È anche molto importante modulare il sistema e definire come i moduli comunicano tra loro (idealmente su un sistema di eventi)
Non so se esiste una cosa del genere.
Tuttavia, dal momento che stai scrivendo in C, devi incoraggiare esplicitamente la disciplina attorno alla modularità. Ti esorto ad avere un'architettura leggera composta da livelli di astrazione, probabilmente 2 o 3 livelli per iniziare. Ogni livello espone concetti, comportamenti e relazioni a un'utile completezza che il successivo livello di consumo può utilizzare senza dover raggiungere il livello inferiore o il metallo nudo.
All'interno di un livello puoi avere una modularità aggiuntiva, simile alle classi in altre lingue.
Quindi documenterei i livelli e il modo in cui sono disposti l'uno rispetto all'altro, accanto alle interfacce di livello. E poi all'interno di un livello, l'organizzazione al suo interno.
Quando hai questa architettura leggera, avrai una nozione più chiara su dove le cose dovrebbero vivere e, si spera, un'idea migliore di dove cercare l'astrazione e le capacità già esistenti.
Con un'architettura leggera, avrai anche nomi di livelli e altri moduli che facilitano la discussione e accelera la comunicazione con i tuoi colleghi.
Leggi altre domande sui tag c embedded-systems documentation documentation-generation