Conception API: Flexibilité Vs. Facilité d'utilisation

Question

Lors de l'écriture d'une bibliothèque ou de l'API publique d'un module qui sera utilisé par un grand nombre d'autres codes dans divers cas d'utilisation, quel est le meilleur moyen d'équilibrer flexibilité et facilité d'utilisation? Je crois que les deux sont souvent contradictoires, plus vous faites quelque chose de flexible, plus il est difficile de faire quelque chose de bien. Par exemple, le C++ STL utilise des itérateurs, dont les IMHO sont horriblement bas et ennuyeux à travailler, mais en échange ils sont extrêmement flexibles en permettant au même code de fonctionner sur tous les types de conteneurs STL. Un autre exemple est la philosophie de conception de la bibliothèque standard Java, avec ses petites classes très spécifiques conçues pour une modularité et une flexibilité maximales, par rapport à la bibliothèque standard Python, avec sa préférence pour une hiérarchie de classes plus simple. . Comment les choses comme celles-ci devraient-elles être équilibrées?

Answer 1

Si vous faites partie d'un organisme de normalisation qui peut imposer l'utilisation de vos classes sur d'autres, vous pouvez aller avec flexible et compliqué (par exemple stl).

Pour tout le monde, à moins qu'il y ait des raisons vraiment convaincantes, la facilité d'utilisation devrait toujours être votre premier choix. Sinon, peu de personnes utiliseront votre code/API. Si la courbe d'apprentissage pour utiliser le code de quelqu'un d'autre est élevée, la plupart des gens choisissent de réimplémenter uniquement les parties dont ils ont besoin. C'est généralement beaucoup plus rapide et les problèmes sont plus faciles à résoudre. À mon avis, la «facilité de compréhension» est la deuxième seulement à «ça fonctionne correctement» quand il s'agit d'évaluer la qualité du code.

En conclusion, si l'ajout de flexibilité se fait au détriment de la facilité d'apprentissage et d'utilisation, n'accroissez pas la flexibilité tant que la flexibilité n'est pas prouvée.

Answer 2

Je pense que vous devez considérer le public cible de la bibliothèque - si vous écrivez une bibliothèque que les développeurs moins expérimentés peuvent bien utiliser, vous devez penser à la façon de les aider. Dans le cas de la STL C++, la plupart des développeurs qui les utilisent ne sont pas dérangés par la mécanique supplémentaire, car ils sont habitués à cela et apprécient beaucoup plus la flexibilité.

Vous voudrez peut-être penser à deux niveaux d'accès via votre API, qui a un niveau qui permet de garder les choses simples et une couche qui permet plus de contrôle. Mais vous voudrez peut-être voir comment le cadre se développe avant d'aller aussi loin.

Answer 3

Je suis friand de l'API de la bibliothèque de classes de base .NET. La conception de la bibliothèque la plus suit these guidelines.

En lisant ces derniers, et le livre qui l'accompagne, j'ai pris plusieurs éléments clés de la connaissance:

1. L'API a été conçu en gardant à l'esprit que les éditeurs modernes ont des capacités de IntelliSense. Les noms plus longs sont acceptables, car vous pouvez mettre en tabulation les noms complets des classes et des méthodes. Ceci est en opposition avec les fonctions de style C avec des noms plus courts et obfusqués comme strnicmp()

2. Utilisation du pattern Create, Set, Call: Toujours avoir un constructeur par défaut, sans paramètre. Fournissez des propriétés qui peuvent être définies dans n'importe quel ordre, puis autorisez les méthodes à être appelées. L'utilisation de ce modèle permet à un objet d'être dans un état non valide pendant une courte période de temps. (Après que le constructeur a été appelé, mais avant que toutes les propriétés ont été définies) Mais c'est correct. Vous pouvez signaler une mauvaise utilisation de l'API en lançant des exceptions. Cela rend l'utilisation de la classe plus accessible.