Diseño de API: Flexibilidad vs. Facilidad de uso

Question

Al escribir una biblioteca o la API pública de un módulo que será utilizado por muchos otros códigos en una variedad de casos de uso, ¿cuál es la mejor manera de equilibrar la flexibilidad con la facilidad de uso? Creo que los dos a menudo entran en conflicto en eso, cuanto más flexible sea usted para hacer algo, más difícil será lograr que haga bien una cosa en particular.

Por ejemplo, STL el C++ utiliza iteradores, que en mi humilde opinión son terriblemente bajo nivel y molesto para trabajar con, pero a cambio de que son extremadamente flexible en permitir que el mismo código para operar en todo tipo de contenedores STL. Otro ejemplo es la filosofía de diseño de la biblioteca estándar de Java, con sus clases pequeñas y muy específicas diseñadas para una modularidad y flexibilidad máximas frente a la biblioteca estándar de Python, con su preferencia por una jerarquía de clases más plana que simplifica el manejo de los casos de uso común. . ¿Cómo deberían ser equilibradas cosas como estas?

Answer 1

Si usted es parte de un organismo de normalización que pueden hacer cumplir el uso de sus clases sobre los demás, entonces se puede ir con (por ejemplo STL) flexible y complicada.

Para todos los demás, a menos que haya algunas razones realmente apremiantes, la facilidad de uso siempre debe ser su primera opción. De lo contrario, pocas personas usarán tu código/API. Si la curva de aprendizaje para usar el código de otra persona es alta, la mayoría de las personas optarán por volver a implementar solo las partes que necesitan. Por lo general, es mucho más rápido y los problemas son más fáciles de resolver.

En mi opinión, la "facilidad de comprensión" ocupa el segundo lugar después de "Funciona correctamente" cuando se trata de calificar la calidad del código.

Por lo tanto, en resumen, si la flexibilidad añadida se consigue a expensas de su facilidad de aprendizaje y uso, entonces no agregue la flexibilidad hasta que NO SE PROBABLE que la flexibilidad es necesaria.

Answer 2

Creo que debe tener en cuenta la audiencia objetivo de la biblioteca: si está escribiendo una biblioteca que los desarrolladores menos experimentados pueden usar, debe pensar cómo ayudarlos. En el caso del C++ STL, probablemente la mayoría de los desarrolladores que los utilizan no les importa la mecánica extra porque están acostumbrados a ellos y valoran mucho más la flexibilidad.

Es posible que desee pensar en dos niveles de acceso a través de su API, que tiene un nivel que mantiene las cosas simples y una capa que permite un mayor control. Pero es posible que desee ver cómo se desarrolla primero el marco antes de llegar a ese extremo.

Answer 3

Me gusta la API de biblioteca de clase base de .NET. El diseño de la biblioteca más sigue these guidelines.

Durante la lectura de estos, y el libro de acompañamiento, que tomó varias piezas clave de conocimiento:

1. la API se ha diseñado teniendo en cuenta que los editores modernos tienen capacidades de IntelliSense. Los nombres más largos son aceptables porque puede tabular los nombres completos de clase y método. Esto está en oposición a las funciones de estilo C con nombres más cortos y ofuscados, como strnicmp()

2. Uso del patrón Crear, configurar, llamada: siempre tiene un valor predeterminado, no es un constructor de parámetros. Proporcione propiedades que se puedan establecer en cualquier orden, y luego permita que se llamen los métodos. El uso de este patrón permite que un objeto se encuentre en un estado inválido durante un corto período de tiempo. (Después de que se llamó al constructor, pero antes de que se establecieran las propiedades) Pero esto está bien. Puede comunicar el uso indebido de API arrojando excepciones. Esto hace que usar la clase sea más accesible.