Quand une API overengineered? [fermé]

Question

Je déteste travailler avec les API overengineered qui ne font pas les choses simples simples. Quoi qu'il en soit, je travaille sur la conception d'une API pour une bibliothèque open source et je commence à sentir que je tombe dans le piège de overengineering. Je ne peux pas dire avec certitude parce que, bien sûr, je l'ai écrit la chose darn, alors comment cela fonctionne est plus évident pour moi que quelqu'un d'autre. Quels sont les signes avant-coureurs du point de vue d'un développeur que votre API peut être overengineered?

Answer 1

« Quels sont les signes avant-coureurs du point de vue d'un développeur que votre API pourrait être overengineered? »

Aucun cas d'utilisation.

Si vous ne pouvez pas exécuter par simple « pour ce faire » scénarios, vous n'êtes pas concevoir une API utile avec des cas d'utilisation spécifiques à l'esprit.

Votre documentation devrait être les cas d'utilisation.

Les fonctionnalités qui ne traitent pas directement les cas d'utilisation sont probablement trop d'ingénierie.

Answer 2

Vous devriez vérifier le Google Tech Talk Comment concevoir une bonne API et son importance par Joshua Bloch ... il couvre beaucoup de ce genre de choses.

Answer 3

Une astuce que j'ai trouvé très utile et il m'a aidé dans le passé est écrire doc avant, pendant et après votre code.

Lors de la conception d'une API à utiliser par d'autres personnes que je documentons habituellement la conception avant l'écriture de code. Si je l'ingénierie sur la conception, la spécification de conception généralement plein de conflits et non-sens.

Au cours de codage, je Stub habituellement la définition de la classe et le corps de la fonction et commencer à écrire des commentaires doxygen pour eux. Dans les commentaires que je vais avoir cas d'utilisation, des exemples de code, et les hypothèses des interfaces. Au cours de cette phase, avant que le code réel est trop écrit, l'interface de classe généralement disparu par la refonte à plusieurs reprises. Je sais que je suis sur l'ingénierie lorsque le code d'échantillon est difficile d'écrire et j'ai du mal à expliquer l'interface. Beaucoup de mauvaises idées de conception sont exposés et éliminés lorsque vous essayez d'expliquer aux gens comment utiliser votre API.

Après le codage, je remplace l'exemple de code dans les commentaires avec le Real compilé et testé le code copié de mes tests unitaires et d'autres documents du comportement de l'interface. Un autre signe de plus d'ingénierie est quand mes tests unitaires ne peuvent pas suivre le changement d'interface, car il y a trop de pièces mobiles et trop de façons de faire les mêmes tests de chose et l'unité de croissance à une proportion exponentielle.

Answer 4

lorsque la trace de la pile pour un appel commun api vous oblige à faire défiler l'écran pour voir la chose entière.

Answer 5

Lors de l'examen de la documentation et des exemples, le pourcentage de verbiage discuter de l'API par rapport à lui-même cmpared au pourcentage de verbiage discuter de son application à des cas d'utilisation crédible.

Answer 6

Comme dit S. Lott, cas d'utilisation. Ils détermineront exactement ce que votre API doit être orientée vers la pratique. Si vous concevez votre API pour compléter un très clair, objectif spécifique - fonctionnellement cohérente - vous êtes plus susceptible de se retrouver avec une API ou d'un composant dans votre API qui est à la fois facile à utiliser et à comprendre.

La conception d'une API devrait être comme la conception d'une interface utilisateur. La plupart de tous les concepts de l'interface utilisateur peuvent être adoptés par une API, par exemple, le principe KISS ou même Kaizen.

Je lier à ces concepts de l'interface utilisateur, mais je suis un nouvel utilisateur afin qu'ils ne me laisse pas poster plus de 1 lien hypertexte. Bon exemple là-bas. StackOverflow, laissez-nous savoir avant de poste;)

Answer 7

Deux (liés) questions à vous poser viennent à l'esprit immédiatement:

• Y at-il des choses qui peuvent être faites dans plus d'une façon?
• sont les méthodes / propriétés il sur l'API qui peut être exprimé en termes du reste de l'API?

Plus difficile à répondre, et non un signe de overengineering en soi, mais sans aucun doute un signe de l'API est pas aussi simple que cela pourrait être encore:

• Y at-il d'autres méthodes / propriétés, vous pouvez introduire qui permettrait de retirer plus que vous présenté (basé sur les deux autres questions)

Answer 8

Quand il est si intelligent que personne ne peut le comprendre.

Answer 9

commencez à vous inquiéter lorsque vous avez une grande API avec beaucoup de fonctions qui, de plus près, se révèlent être des compositions d'opérations plus simples. Une API avec un taux élevé de mécanismes de composition aux primitives est généralement une bonne conception.

(conception API est très similaire à la conception du langage, et ici, je suis essentiellement épousait le schéma philosophie au lieu d'empiler plusieurs routines dans l'API, simplifier et inclure des mécanismes de composition qui rendent les routines supplémentaires inutiles.)

Answer 10

Dans mon expérience, vous pouvez dire quand l'ensemble du projet est maintenu pendant des mois, dans l'attente de l'API à terminer.

Answer 11

Lorsque vous utilisez l'API est: (1) plus obtus, plus complexe, moins efficace et moins prévisible que la simple utilisation de la technologie sous-jacente, ET (2) n'offre pas un avantage significatif pour la sécurité, l'évolutivité ou la liberté multiplateformes.