Si parla di quale sintassi e caratteristica ti piace in un linguaggio di programmazione; ora chiederò quali principi di base o funzionalità vorresti in una libreria nella tua lingua preferita (o in qualsiasi altra lingua)?
Un esempio sta avendo l'aggiunta di lista + = anotherList come oppose alla sola lista consentita + = listElement (anche se alcuni potrebbero vederla come una cattiva idea)
Seguirò le migliori pratiche che puoi trovare in Come progettare una buona API e perché è importante per Joshua Blosh (Google) . La versione PDF può essere trovata qui .
Secondo lui, le caratteristiche di una buona API sono:
Easy to learn
Easy to use, even without documentation
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to extend
Appropriate to audience
Voglio quanto segue:
Uno spazio dei nomi chiaramente definito. Dal momento che C è la mia lingua principale, voglio anche che le macro corrispondano a questa. Risolvere i conflitti in quell'area fa schifo.
Se assegni qualcosa, dammi qualche indizio evidente che deve essere liberato. Questo va al mio prossimo punto, che è la documentazione.
Documenta la libreria. Strumenti come Doxygen sono semplici e portatili, non ci sono scuse per non darmi qualcosa che posso generare e sfogliare.
Documento di tipi opachi nelle intestazioni pubbliche. Li troverò comunque, dimmi perché non vuoi che mi incasini con loro e cosa potrebbe succedere se lo faccio. Se effettivamente vuoi le patch, ho bisogno di sapere cosa stavi pensando.
Non lasciar cadere ed eseguire. Apprezzo molto i commenti come "Per favore, non contattarmi per questo.Non ho intenzione di mantenerlo.Questo ha risolto il mio problema immediato, forse risolverà il tuo problema.Non mi interessa, non sono andando ad aggiornare questo e puoi sentirti libero di sborsarlo. " Non posso dirti quanto tempo mi risparmia.
Non dovrebbe aggiungere perdite di memoria o errori nel codice esistente. Se non esegui test prima di spingere cose sul tuo codice, perché mi stai tentando di spingerlo al mio?
Se si tratta effettivamente di una libreria, utilizzare una licenza permissiva ed essere coerenti. Non decidi tra tre mesi che dovresti fare più soldi con questo. Ciò è oltre la fastidiosa notte prima di spedire qualcosa e rendersi conto che è necessario riscrivere un po 'di codice della libreria perché la licenza è cambiata. Questo è esattamente il tipo di cosa che mi rende abbastanza irritato per ri-implementare i tuoi contenuti sotto la licenza del MIT.
Siate coerenti nello stile di codifica, le altre persone devono leggere il vostro codice per capire cosa sta effettivamente facendo quando le cose non funzionano come previsto.
Non utilizzare più di 110 colonne, potrebbe essere necessario modificare il codice in atto e potrei avere solo un display 80x25. Se ti affidi alle schede per rendere le cose più "eleganti", hai altri problemi da risolvere.
Cerca almeno di considerare le porte, se non si tratta di una lingua interpretata. Anche in questo caso, prova almeno a considerare le porte.
Fammi testare. Spero che tu li abbia, potrei suggerirli diversamente e in realtà potrei aiutarli a scriverli sulla base di un grafo delle chiamate. Se devo affrontare tutti questi problemi, gentilmente, usali . Altrimenti, ottieni patch che "funzionano per me !!!" :)
Non interrompere l'API, punto. So che potresti capire che hai sbagliato tutto, ma assicurati che le cose che ti riguardano non si interrompano su un semplice aggiornamento. Ciò potrebbe significare cruft e kludges, benvenuti nel mondo delle biblioteche.
Forniscimi una tabella di marcia in modo da non duplicare il tuo lavoro o il lavoro degli altri.
Probabilmente modificherò questo post per aggiungerne altri.
Sono più preoccupato per le funzionalità software di un'API. Cioè:
Potrei avere ragione su un libro su come applicare o essere implementato, ma basti dire che a meno che un utente dell'API non riesca a capire come utilizzarlo in modo efficace, è di uso limitato. La semplicità non significa semplicismo, proprio come l'eleganza non significa onate. Significa semplicemente che è semplicemente perfetto per il lavoro. Meno persone devono pensare a come utilizzare l'API, più possono semplicemente usarlo.
In che modo questi aspetti dipendono dall'Innage, dallo scopo e dal pubblico di destinazione dell'API. L'ultimo criterio si riduce al principio di minima sorpresa. Nessun errore in cui non ti aspettavi. Qualsiasi ragionevole interpretazione dell'API ti darà i risultati che desideri.
Questo praticamente riassume ogni altra filosofia di design. Se la tua libreria rende solo le cose complicate possibili, le persone che cercano di risolvere il più semplice 80% dei casi d'uso saranno tentate di reinventare la ruota piuttosto che affrontare la mostruosità eccessivamente ingegnosa che richiede l'utilizzo di 6 classi diverse per fare l'equivalente della biblioteca di "Ciao World".
Se la tua libreria semplifica le cose semplici, le persone si arrabbieranno molto rapidamente quando scopriranno che hanno bisogno di riscrivere il loro codice solo perché avevano un requisito un po 'fuori mano.
I modi migliori per farlo sono:
Sii liberale in ciò che accetti. Se stai programmando in un linguaggio dinamico, usa la digitazione anatra a pieno effetto. Se stai programmando in C ++ o D, usa i modelli ovunque sia possibile. Accetta tutto ciò che soddisfa un'interfaccia strutturale ragionevolmente universale. Non costringere i tuoi utenti a fare un sacco di lavoro impegnato a convertire i dati da un formato all'altro.
Crea funzionalità di alto livello nella tua libreria, ma crea in modo trasparente le funzionalità di livello inferiore e assicurati che la funzionalità di livello inferiore sia disponibile per le persone che ne hanno bisogno.
Seguire il principio della meno sorpresa per impostazione predefinita, anche se ciò potrebbe limitare la flessibilità o l'efficienza. Se necessario, aggiungi una seconda funzione con un nome più dettagliato che enfatizzi la sua sorprendentezza per consentire ottimizzazioni o maggiore flessibilità.
L'incapsulamento è utile, ma non essere anale a riguardo. Le persone con esigenze insolite e inaspettate potrebbero occasionalmente aver bisogno di passare sotto una delle tue astrazioni per portare a termine il lavoro. D'altra parte, dovrebbe essere difficile spararsi sul piede per caso, quando si usano costrutti apparentemente innocenti . Tienilo a mente quando decidi quanto vuoi bloccare le cose.
Utilizzare gli esempi pesantemente nella documentazione. Questo serve sia per illustrare casi di uso comune all'utente che per costringerti a pensare se i casi più comuni siano sufficientemente ottimizzati.
Avere impostazioni predefinite ragionevoli per tutto ciò che puoi, ma assicurati che quelle di default siano solo predefinite e che sia chiaro come sovrascriverle.
Questo è tutto. Confronta, ad esempio, il meccanismo delle pipe su Windows e UNIX. Uno offre una serie di funzioni API specializzate con una serie di argomenti oscuri, non necessari o usati raramente, ognuno dei quali può avere uno dei tanti valori di macro / costanti. Fondamentalmente UNIX riutilizza l'interfaccia esistente aperta / lettura / scrittura / chiudi, oltre ad alcuni metodi molto semplici per alcuni casi specifici, come socketpair () o pipe (). C'è davvero quasi, quasi nulla di nuovo che dovresti imparare per usare pipe su UNIX. Ora confronta con questo .
(Per essere onesti, Microsoft in origine aveva solo "preso in prestito" quell'interfaccia dall'OS / 2 di IBM.)
Leggi altre domande sui tag design interfaces api libraries