Sto lavorando a un progetto Arduino usando Uno. Il progetto contiene una quantità significativa di codice. Vorrei creare una biblioteca e potrei anche condividerla in seguito. Quali linee guida devo seguire durante la progettazione della biblioteca?
Risposte:
Ci sono molti punti da tenere a mente durante la progettazione di una libreria. Come probabilmente finirai per condividere il tuo lavoro con gli altri, è estremamente importante seguire modelli di progettazione coerenti. Tieni presente che gli altri utenti avranno livelli di abilità estremamente variabili, quindi progetta una libreria di facile utilizzo, nella massima misura possibile.
Fornisci una mappa pin di base che la tua libreria si aspetta. Non mantenere statica la mappatura dei pin ma consentire all'utente di apportare facilmente modifiche.
Una delle prime cose che dovresti provare a garantire è che la tua libreria funzioni. In caso contrario, dichiaralo chiaramente. Non vorrai finire per perdere tempo a cercare di lavorare con software non funzionante, quindi non lasciare che anche gli altri lo facciano.
Indica chiaramente quali schede sono state progettate per la libreria, su quali sono state testate e su quali schede dovrebbe funzionare. Specifica la generazione (versione) di ogni scheda menzionata qui.
La prossima cosa è che dovresti avere interfacce chiaramente definite. Una biblioteca funzionante con interfacce contorte è frustrante. Questo ti aiuterà a utilizzare la libreria in un secondo momento e renderà le cose più facili per gli altri utenti. Questo dovrebbe essere uno degli aspetti più importanti da tenere a mente.
Che tu segua un approccio top-down o bottom-up, le interfacce dovrebbero essere sempre chiare nella tua mente. In un approccio dal basso verso l'alto, questo può e sarà difficile, ma non dovrebbe essere ignorato. Altrimenti, finirai con una libreria troppo complessa che potrebbe non essere utilizzabile.
Se si dispone di funzioni che utilizzano alcune caratteristiche speciali della scheda, assicurarsi di farle risaltare, menzionarle nel file Leggimi e anche nei commenti.
Potrebbero esserci scenari in cui potresti dover utilizzare un'attesa di occupato. Tali funzioni, a seconda della logica del programma, possono impedire il normale flusso di controllo, causando problemi nel mezzo di un'attività critica. Prova a usare interrupt o altri algoritmi, se possibile. In caso contrario, menzionare chiaramente contrassegnare tali funzioni.
Assicurati di commentare ogni piccola e grande modifica apportata. Scrivi bei commenti lunghi per tutte le funzioni critiche e quelle più piccole per gli altri. Descrivi esplicitamente la tua interfaccia, ogni argomento, cosa fa e cosa restituisce. Questo è molto lavoro extra, ma sarà immensamente utile sia per te che per gli altri. Se hai delle funzioni che potrebbero non funzionare su schede diverse, menzionale qui. Se queste sono funzioni intermedie utilizzate da altre funzioni e possono essere necessarie, menzionate nel file Leggimi.
Assicurati che tutto, anche i commenti, siano coerenti nei file .he .cpp.
Conserva solo le funzioni correlate all'interno di un singolo file. Avere alcuni moduli piccoli, ma logicamente coerenti, è meglio di un enorme file con tutto ciò che contiene.
Scrivi un file readme chiaro che descriva la libreria, le sue capacità, eventuali problemi o bug e l'usabilità di base. Utilizzare un file separato per definire e spiegare ciascuna interfaccia come descritto sopra.
Una volta che la libreria diventa grande, può essere necessario dividerla in directory. Questo non è facilmente possibile durante l'utilizzo di Arduino-Ie . Ma, se sei arrivato così lontano, probabilmente sei un utente Arduino avanzato e usi strumenti di sviluppo più potenti. Altrimenti, questo è l'universo che ti dice di farlo.
Assicurati di aggiungere una licenza.
Utilizzare uno strumento VCS come Git o SVN. Ciò renderà molto più semplice visualizzare le modifiche apportate, ripristinare le versioni precedenti, individuare errori che causano codice e persino collaborare con altri.
La risposta di AshRj è molto buona: ho solo 2 punti da aggiungere.
Punto 1: documentazione
AshRj ha raccomandato di scrivere un readme dettagliato. Mentre questa può essere una buona pratica, può sfuggire rapidamente a librerie più grandi - in effetti, anche a poche migliaia di righe (il che non è molto), un readme non avrà quasi alcun vantaggio. La mia raccomandazione sarebbe di fare un ulteriore passo avanti e usare l'equivalente di Javadocs per C ++ - come spiega questa risposta (è su Stack Overflow), Doxygen è uno strumento molto utile per mantenere la documentazione gestibile e a portata di mano (nessuno vuole modificare un File Leggimi di riga 10K ...)
Punto 2: Directory
Di nuovo in contrasto con la risposta di AshRj, usa sempre le directory. Anche se hai solo 10 file, forse anche solo con 7 o 8. So che sembra un po 'stupido, ma il tuo lavoro è a prova di futuro e se non inizi in anticipo finirai con un casino di File. Le directory non sono solo per progetti di grandi dimensioni, ma anche quelle piccole dovrebbero usarle. Basta ricordare che in C ++ (il linguaggio di fatto di Arduino), le directory vengono ignorate quando si includono file da una libreria - esistono solo come strumento di gestione del codice.