Quali linee guida dovrei seguire durante la progettazione di una libreria?

11

Sto lavorando su un progetto Arduino usando lo Uno. Il progetto contiene una quantità significativa di codice. Vorrei creare una libreria e potrei anche condividerla in seguito. Quali linee guida dovrei seguire durante la progettazione della libreria?

    
posta asheeshr 11.04.2013 - 16:08
fonte

2 risposte

12

Ci sono molti punti che dovresti 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 design coerenti. Tieni presente che gli altri utenti avranno livelli di abilità estremamente variabili, quindi progetta una libreria facile da usare, nella massima misura possibile.

Suggerimenti di base

Mappa dei pin

Fornisci una mappa pin di base che la tua biblioteca si aspetta. Non mantenere la mappatura dei pin statica ma consentire all'utente di apportare modifiche facilmente.

Libreria di lavoro

Una delle prime cose che dovresti cercare di assicurare è che la tua libreria funzioni. Se non lo è, affermalo chiaramente. Non vorrai finire a perdere tempo a cercare di lavorare con software non funzionanti, quindi non lasciare che anche gli altri facciano altrettanto.

Readme di base

Indicare con chiarezza quali schede sono state progettate per la libreria, su cui è stato testato, e quale scheda (e) è prevista che funzioni. Specifica la generazione (versione) di ogni tavola menzionata qui.

Interfacce

La prossima cosa è che dovresti avere interfacce chiaramente definite. Una libreria funzionante con interfacce complesse è frustrante. Ciò ti aiuterà a utilizzare la libreria in un secondo momento e renderà le cose più facili agli altri utenti. Questo dovrebbe essere uno degli aspetti più importanti da tenere a mente.

Sia che seguiate un approccio dall'alto verso il basso o dal basso verso l'alto, le interfacce dovrebbero essere sempre chiare nella vostra mente. Con un approccio dal basso verso l'alto, questo può e sarà difficile, ma non dovrebbe essere ignorato. Altrimenti, finirai con una libreria eccessivamente complessa che potrebbe non essere utilizzabile.

Funzioni speciali

Se hai qualche funzione che utilizza alcune caratteristiche speciali della scheda, assicurati di far risaltare queste funzioni, menzionando nel readme e anche nei commenti.

Occupato attende

Potrebbero esserci degli scenari in cui potrebbe essere necessario attendere molto. Tali funzioni, a seconda della logica del programma, possono impedire il normale flusso di controllo, causando problemi mentre si è nel mezzo di un'attività critica. Prova a utilizzare interrupt o altri algoritmi, se possibile. In caso contrario, quindi chiaramente menzionare contrassegnare tali funzioni.

Commenti

Assicurati di continuare a commentare ogni piccola e grande modifica che apporti. 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 è un lavoro extra, ma sarà immensamente utile sia per te che per gli altri. Se hai qualche funzione che potrebbe non funzionare su una o più schede diverse, menzionala qui. Se queste sono funzioni intermedie utilizzate da altre funzioni e potrebbero essere necessarie, menzionate nel file Leggimi.

Coerenza

Assicurati che tutto, anche i commenti, siano coerenti tra i file .h e .cpp .

Conserva solo le funzioni correlate all'interno di un singolo file. Avere pochi moduli piccoli, ma logicamente coerenti, è meglio di un enorme file con tutto ciò che contiene.

Suggerimenti avanzati

Readme dettagliato

Scrivi un chiaro file readme che descriva la libreria, le sue capacità, eventuali problemi o bug e usabilità di base. Utilizzare un file separato per definire e spiegare ciascuna interfaccia come descritto sopra.

Struttura delle directory

Una volta che la libreria diventa grande, potrebbe essere necessario dividerla in directory. Questo non è facilmente possibile quando si utilizzano le . Ma, se sei arrivato così lontano, probabilmente sei un utente avanzato di Arduino e usi strumenti di sviluppo più potenti. Altrimenti, questo è l'universo che ti dice di farlo.

Licensing

Assicurati di aggiungere una licenza.

Controllo versione

Utilizza uno strumento VCS come Git o SVN. Ciò renderà molto più facile vedere le modifiche apportate, ripristinare le versioni precedenti, individuare errori che causano codice e persino collaborare con altri.

    
risposta data 11.04.2013 - 16:08
fonte
2

La risposta di AshRj è molto buona - ho solo 2 punti da aggiungere ad essa.

Punto 1: Documentazione

AshRj raccomanda di scrivere un readme dettagliato. Anche se questo può essere una buona pratica, può rapidamente sfuggire di mano con le biblioteche più grandi - anzi, anche a poche migliaia di righe (che in realtà non è molto), un readme non avrà quasi alcun beneficio. La mia raccomandazione sarebbe di fare un ulteriore passo avanti e utilizzare l'equivalente di Javadocs per C ++ - come questa risposta spiega (è su Stack Overflow), Doxygen è uno strumento molto utile per mantenere la documentazione gestibile e a portata di mano (nessuno vuole modificare un file readme della linea 10K ...)

Punto 2: directory

Di nuovo in contrasto con la risposta di AshRj, sempre usa le directory. Anche se hai solo 10 file, forse anche con solo 7 o 8. So che sembra un po 'stupido, ma è a prova di futuro il tuo lavoro, e se non inizi presto ti ritroverai con un casino di File. Le directory non sono solo per i progetti di grandi dimensioni - anche le più piccole dovrebbero utilizzarle. Ricorda che in C ++ (il linguaggio di fatto di Arduino), le directory vengono ignorate quando includono i file di una libreria - esistono solo come strumento di gestione del codice.

    
risposta data 11.04.2013 - 17:21
fonte

Leggi altre domande sui tag