Comment définissez-vous une bonne ou une mauvaise API?
Fond:
Je prends une classe à mon université appelée "contraintes logicielles". Dans les premières conférences, nous apprenions à construire de bonnes API.
Un bon exemple que nous avons obtenu d'une très mauvaise fonction API est la prise public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); en C #. La fonction reçoit 3 listes de sockets et les détruit à la fabrication de l'utilisateur pour cloner toutes les prises avant de les alimenter dans la Select(). Il a également un délai d'attente (en microsecondes) qui est un int, qui définit le maximum de temps que le serveur peut attendre une prise. Les limites de ceci sont de +/- 35 minutes (parce que c'est un int).
Des questions:
- Comment définissez-vous une API comme "mauvais"?
- Comment définissez-vous une API comme "bon"?
Points à considérer:
- Les noms de fonction difficiles à retenir.
- Paramètres de fonction difficiles à comprendre.
- Mauvaise documentation.
- Tout est donc interconnecté que si vous devez modifier 1 ligne de code, vous devrez réellement modifier des centaines de lignes dans d'autres endroits.
- Fonctions qui détruisent leurs arguments.
- Mauvaise évolutivité en raison de la complexité "cachée".
- Il est requis de l'utilisateur/dev de construire des emballages autour de l'API afin qu'il puisse être utilisé.
Dans API Design j'ai toujours trouvé ce notnote très utile:
[.____] Comment concevoir une bonne API et pourquoi cela compte - par Joshua Bloch
Voici un extrait, je recommanderais de lire le tout/regarder la vidéo.
II. Principes généraux
- API devrait faire une chose et le faire bien
- API devrait être aussi petit que possible mais pas plus petit
- La mise en œuvre ne devrait pas avoir une incidence sur l'API
- Minimiser l'accessibilité de tout
- Les noms importants-API sont une petite langue
- Documentation matière
- Documenter religieusement
- Pensez aux conséquences de la performance des décisions de conception de l'API
- Effets des décisions de conception de l'API sur la performance sont réelles et permanentes
- API doit coexister paisiblement avec la plate-forme
III. Conception de classe
- Minimiser la mutabilité
- Sous-classe seulement où cela a du sens
- Conception et document pour l'héritage ou d'autre l'interdire
Iv. Conception de la méthode
- Ne faites rien que le client ne puisse rien que le module puisse faire
- Ne violez pas le principe du moins d'étonnement
- FAIL FAST - Signaler des erreurs dès que possible après qu'ils se produisent
- Fournir un accès programmatique à toutes les données disponibles sous forme de chaîne
- Surcharge avec soin
- Utilisez des types de paramètres et de retour appropriés
- Utilisez un paramètre cohérent de commande entre méthodes
- Évitez les listes de paramètres longues
- Évitez les valeurs de retour qui exigent un traitement exceptionnel
Vous n'avez pas à lire la documentation pour l'utiliser correctement.
Le signe d'une API impressionnante.
De nombreuses normes de codage et documents plus longs et même Livres (Livres (Livres de conception-cadre) ont été écrits sur ce sujet, mais une grande partie ne peut qu'à un niveau assez bas.
Il y a aussi une question de goût. Les API peuvent obéir à chaque règle dans tout le livre de règles et sucer toujours, en raison de l'adhérence esclave à diverses idéologies in-vogues. Un coupable récent est une orientation de modèle, dans laquelle des modèles de singleton (peu plus que des variables globales initialisées) et des motifs d'usine (un moyen de la construction de paramétrage, mais souvent mis en œuvre lorsqu'il n'est pas nécessaire) sont surutilisés. Dernièrement, il est plus probable que l'inversion du contrôle (CIO) et une explosion associée dans le nombre de minuscules types d'interfaces qui ajoute une complexité conceptuelle redondante aux conceptions.
Les meilleurs tuteurs à goûter sont l'imitation (lisant beaucoup de code et d'API, découvrant ce qui fonctionne et ne fonctionne pas), de l'expérience (en faisant des erreurs et d'en apprendre de cela) et de penser (ne faites pas simplement ce qui est à la mode pour son saké, pense avant d'agir).
ne bonne API a un modèle sémantique proche de la chose qu'elle décrit.
Par exemple, une API pour créer et manipuler des feuilles de calcul Excel aurait des cours comme Workbook, Sheet et Cell, avec des méthodes telles que Cell.SetValue(text) et Workbook.listSheets().
Une bonne API permet au client de faire à peu près tout ce dont ils ont besoin de faire, mais ne leur nécessitent pas de faire beaucoup de travail occupé. Des exemples de "travaux techniques méfiant" permettraient d'initialiser des champs de structure de données, appelant plusieurs routines dans une séquence qui ne varie jamais avec aucun code personnalisé réel entre, etc.
Le signe le plus sûr d'une mauvaise API est si vos clients souhaitent tous le cailler avec leur propre code d'aide. Au moins absolu, votre API aurait dû fournir ce code d'aide. Très probablement, il aurait dû être conçu pour fournir le niveau d'abstraction plus élevé que les clients se roucent à chaque fois.
J'ai toujours aimé cet article dans la file d'attente intitulée API Design Matters
http://quue.acm.org/detail.cfm?id=1255422
Et ces colonnes qui traitent également des problèmes de conception de l'API:
Une mauvaise API est une API qui n'est pas utilisée par son public cible.
Une bonne API est une bonne API qui est utilisée par son auditoire prévu à cet effet pour lequel il a été conçu.
Une grande API est une API qui est utilisée à la fois par son auditoire prévue, pour le but recherché et un public imprévu pour des raisons imprévues par ses concepteurs.
Si Amazon publie son API comme =SOAP et repose, et le REST Version gagne, cela ne signifie pas le sous-jacent SOAP Api était mauvais.
J'imagine que la même chose sera vraie pour vous. Vous pouvez lire tout ce que vous voulez sur la conception et faire de votre mieux, mais le test d'acide sera utilisé. Passez du temps à construire de manière à obtenir des commentaires sur les travaux et ce qui ne fonctionne pas et soyez prêt à refacteur au besoin pour le rendre meilleur.
Une bonne API est une bonne asile qui fait des choses simples simples (une bouilloire minimale et une courbe d'apprentissage pour faire les choses les plus courantes) et des choses compliquées possibles (flexibilité maximale, aussi peu d'hypothèses que possible). Une API médiocre est une API qui fait partie de ces puits (sans danger, mais seulement si vous essayez de faire des choses vraiment fondamentales, ou non puissant, mais avec une courbe d'apprentissage vraiment escarpée, etc.). Une API horrible est une API qui ne fait aucun de ces puits.
Il y a déjà plusieurs autres bonnes réponses à ce sujet, alors je pensais que je voudrais juste jeter des liens que je n'ai pas vu mentionné.
Des articles
- "Un petit manuel de la conception API" de Jasmin Blanchette de TrollTech
- "Définition de API de style QT C++" aussi Trolltech
Livres:
Je pense qu'une bonne API devrait autoriser personnalisé IO et crochets de gestion de la mémoire s'il est applicable.
Un exemple typique Vous avez votre format d'archive compressé personnalisé pour les données sur le disque et une bibliothèque tierce avec une API médiocre souhaite accéder aux données sur disque et s'attend à ce qu'un chemin d'accès à un fichier dans lequel elle puisse charger ses données.
Ce lien a de bons points: http://gaquesaratect.net/2008/09/19/good-middleware/
Si l'API produit un message d'erreur, assurez-vous que le message et les diagnostics aident un développeur à déterminer quel est le problème.
Mon attente est que l'appelant d'une API passe en entrée qui est correct. Un développeur est le consommateur de tout message d'erreur produit par l'API (pas l'utilisateur final) et les messages destinés au développeur aident le développeur déboguer de leur programme d'appel.
Une API est mauvais quand il est mal documenté.
Une API est Bon quand il est bien documenté et suit une norme de codage.
Maintenant, il s'agit de deux points très simples et très difficiles à suivre, cela apporte un dans la zone de l'architecture logicielle. Vous avez besoin d'un bon architecte qui structure le système et aide le cadre à suivre ses propres lignes directrices.
Code commentant, écrire un bien expliqué Manuel de l'API est obligatoire.
Une API peut être bonne s'il a une bonne documentation qui explique comment l'utiliser. Mais si le code est propre, bon et suit une norme en elle-même, elle ne comporte pas si elle a une documentation décente.
J'ai un peu écrit sur la structure de codage ici
Je pense que ce qui est primordial est la lisibilité, par laquelle je veux dire la qualité qui rend le plus grand nombre de programmeurs à donner un sens à ce que le code fait dans le temps le plus court possible. Mais à juger quel logiciel est lisible et qui n'est pas cette qualité humaine indescriptible: floue. Les points que vous mentionnez font partiellement la cristallisation. Cependant, dans son intégralité, il doit rester une affaire de cas par cas et il serait vraiment difficile de trouver des règles universelles.