Cosa hanno in comune le grandi API? [chiuso]

Cosa c'è nelle grandi API che le rendono eccezionali? Penso che aderire al mantra "fai una cosa e fallo bene" sia un buon segno ed essere una buona mappatura sul dominio problematico è importante, ma cosa hanno in comune le grandi API?

Devi stare attento a evitare di aggiungere un nuovo vocabolario solo per il bene della tua API. Le mie API preferite mi spiegano le cose nel vocabolario che ho già capito. Lungo queste linee:

Non aggiungere troppe astrazioni oltre a ciò su cui stai costruendo. Mantienilo semplice.

Devo già pensare a una mezza dozzina di strati di astrazione. Non farmi pensare a livelli extra. Non darmi troppe cose nuove da imparare che non aggiungeranno valore al mio obiettivo finale. Ad esempio, evita di usare la tua speciale classe di file che funziona in modo diverso dal tipo di file della lingua solo perché pensi che la tua strada sia migliore di quella generalmente accettata. Attenersi al modo generalmente accettato, almeno nelle interfacce, nel bene e nel male.

Attenersi a idee concrete

Ad esempio, non tentare di nascondere il fatto che la parte "modello" del framework MVC è un front-end per un database. Approfitta del famoso vocabolario che circonda i "database". So cosa sono le chiavi esterne. So cosa sono le righe e le colonne. Parlami in questi termini.

Non astrarre le conoscenze essenziali

Simile a lavorare con idee concrete. Non nascondere il fatto che abbiamo a che fare con file o database o righe nei database. Conosco queste cose. Se ho a che fare con un container, come un elenco, ci sono buone probabilità che io abbia bisogno di conoscere la complessità algoritmica delle operazioni comuni. Puoi semplificare molto dicendo semplicemente che è un "elenco collegato" o un "array". Un'enorme serie di idee verrà improvvisamente messa in pratica per quello che stai facendo e all'improvviso avrà senso. Non creare il tuo set di idee che devo imparare quando arriverò già con un set ricco e utile di terminologia da applicare al problema.

Riduci il numero di termini di cui ho bisogno nel mio vocabolario

Se sto usando la tua API per aprire un file di immagine di qualsiasi tipo, non dovrei pensare molto a pngs vs gifs vs jpgs. Lo farai per me. È la tua competenza principale, non la mia. Ho una vaga comprensione che tu abbia un po 'di magia per fare questo per me.

Un'API utile ha quanto segue:

• Documentazione concisa e approfondita. Se sto cercando come implementare un'attività, sono in grado di scoprire se l'API ha la capacità di farlo, entro un paio di minuti. Ciò è ottenuto dalla brevità del testo e dal layout della risorsa. La documentazione fornisce esempi su come usarlo e inoltre non fa ipotesi sul pubblico.
• Una grande comunità attiva. Sono entusiasta quando trovo forum, canali IRC, mailing list, ecc. Con partecipanti attivi disposti ad aiutare i nuovi ragazzi. Capisco che questo è solitamente il caso di progetti più grandi, ma comunque sarebbe qualcosa su cui lottare.
• Consistenza. Quando sto effettivamente utilizzando l'API, non voglio essere scioccato in alcun modo quando chiamo un metodo o scopro che il metodo Xè completamente diverso dalla convenzione impostata dal resto dell'API.

Le grandi API hanno un'ottima documentazione.

• Fai una cosa e fallo alla grande.
• Facile da usare, difficile da usare in modo improprio.
• Facile da estendere.
• Ben documentato.
• Stile coerente.

Questa domanda è stata affrontata in "Practical API Design: Confessions of a Java Framework Architect" di Jaroslav Tulach del team NetBeans.

L'interfaccia utile più semplice e le buone convenzioni di denominazione.