¿Cómo define una API buena o mala? [cerrado]
https://stackoverflow.com/questions/469161
-
19-08-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianPregunta
Fondo:
Estoy tomando una clase en mi universidad llamada "Restricciones de software". En las primeras conferencias estábamos aprendiendo cómo construir buenas API.
Un buen ejemplo que obtuvimos de una función API realmente mala es el socket public static void Select (IList checkRead, IList checkWrite, IList checkError, int microsegundos); en C #. La función recibe 3 listas de sockets y los destruye, lo que hace que el usuario tenga que clonar todos los sockets antes de alimentarlos al Select () . También tiene un tiempo de espera (en microsegundos) que es un int, que establece el tiempo máximo que el servidor puede esperar un socket. Los límites de esto son +/- 35 minutos (porque es un int).
Preguntas:
- ¿Cómo define una API como 'malo'?
- ¿Cómo se define un ¿API como 'buena'?
Puntos a tener en cuenta:
- Nombres de funciones que son difíciles de recordar.
- Parámetros de función que son difíciles de entender.
- Mala documentación.
- Todo está tan interconectado que si necesita cambiar 1 línea de código, necesitará cambiar cientos de líneas en otros lugares.
- Funciones que destruyen sus argumentos.
- Mala escalabilidad debido a "oculto" complejidad.
- Se requiere del usuario / desarrollador para construir contenedores alrededor de la API para que pueda usarse.
Solución
En el diseño de API siempre he encontrado esta nota clave muy útil:
Cómo diseñar un bien API y por qué es importante: por Joshua Bloch
Aquí hay un extracto, recomiendo leerlo todo / ver el video.
II. Principios generales
- API debería hacer una cosa y hacerlo bien
- API debe ser lo más pequeña posible pero no más pequeña
- La implementación no debería afectar la API
- Minimizar la accesibilidad de todo
- Names Matter & # 8211; API es un lenguaje pequeño
- La documentación importa
- Documento Religioso
- Considere las consecuencias de rendimiento de las decisiones de diseño de API
- Los efectos de las decisiones de diseño de API en el rendimiento son reales y permanentes
- API debe coexistir pacíficamente con la plataforma
III. Diseño de clase
- Minimizar mutabilidad
- Subclase solo donde tiene sentido
- Diseño y documento para herencia o si no lo prohíbe
IV. Diseño del método
- No haga que el cliente haga nada que el módulo pueda hacer
- No viole el principio de menos asombro
- Fail Fast: informe los errores lo antes posible después de que ocurran
- Proporcionar acceso programático a todos los datos disponibles en forma de cadena
- Sobrecarga con cuidado
- Usar parámetros apropiados y tipos de retorno
- Usar ordenamiento de parámetros consistentes entre métodos
- Evite listas largas de parámetros
- Evite los valores de retorno que exigen un procesamiento excepcional
Otros consejos
No tiene que leer la documentación para usarla correctamente.
El signo de una API increíble.
Muchos estándares de codificación y documentos más largos e incluso libros (Directrices de diseño del marco) sobre este tema, pero gran parte de esto solo ayuda a un nivel bastante bajo.
También hay una cuestión de gustos. Las API pueden obedecer todas las reglas en cualquier libro de reglas, y aún apestar, debido a la adhesión servil a varias ideologías en boga. Un culpable reciente es la orientación de patrones, en donde los patrones Singleton (poco más que las variables globales inicializadas) y los patrones de fábrica (una forma de parametrizar la construcción, pero a menudo implementados cuando no se necesitan) se usan en exceso. Últimamente, es más probable que la Inversión de control (IoC) y la explosión asociada en la cantidad de pequeños tipos de interfaz que agregue complejidad conceptual redundante a los diseños.
Los mejores tutores para el gusto son la imitación (leer mucho código y API, descubrir qué funciona y qué no funciona), experiencia (cometer errores y aprender de ello) y pensar (no solo hacer lo que está de moda por eso) propio bien, piensa antes de actuar).
- Útil: aborda una necesidad que aún no se ha satisfecho (o mejora las existentes)
- Fácil de explicar: la comprensión básica de lo que hace debería ser fácil de entender
- Sigue algún modelo de objeto de algún dominio problemático o del mundo real. Utiliza construcciones que tienen sentido
- Uso correcto de llamadas sincrónicas y asincrónicas. (no bloquee las cosas que llevan tiempo)
- Buen comportamiento predeterminado: cuando sea posible, permita la extensibilidad y los ajustes, pero proporcione valores predeterminados para todo lo que sea necesario para casos simples
- Muestra de usos y aplicaciones de muestra de trabajo. Esto es probablemente lo más importante de todo.
- Excelente documentación
- Coma su propia comida para perros (si corresponde)
- Mantenlo pequeño o segméntalo para que no sea un gran espacio contaminado. Mantenga los conjuntos de funciones distintos y aislados con pocas dependencias, si es que las hay.
Hay más, pero ese es un buen comienzo
Una buena API tiene un modelo semántico cercano al que describe.
Por ejemplo, una API para crear y manipular hojas de cálculo de Excel tendría clases como Workbook , Sheet y Cell , con métodos como < code> Cell.SetValue (texto) y Workbook.listSheets () .
Una buena API le permite al cliente hacer casi todo lo que necesita hacer, pero no requiere que haga mucho trabajo sin sentido. Ejemplos de "trabajo ocupado sin sentido" estaría inicializando campos de estructura de datos, llamando a varias rutinas en una secuencia que nunca varía sin un código personalizado real entre ellas, etc.
El signo más seguro de una API incorrecta es si todos sus clientes quieren envolverla con su propio código auxiliar. Como mínimo, su API debería haber proporcionado ese código auxiliar. Lo más probable es que debería haber sido diseñado para proporcionar el mayor nivel de abstracción que los clientes se están haciendo solos cada vez.
Siempre me ha gustado este artículo en la cola titulado API Design Matters
http://queue.acm.org/detail.cfm?id=1255422
Y esta columna también que trata con problemas de diseño de API:
Una API incorrecta es aquella que no está siendo utilizada por su público objetivo.
Una buena API es aquella que utiliza su público objetivo para el propósito para el que fue diseñada.
Una gran API es aquella que es utilizada tanto por su público objetivo, para el propósito previsto, como por un público no intencionado por razones no previstas por sus diseñadores.
Si Amazon publica su API como SOAP y REST, y la versión REST gana, eso no significa que la API SOAP subyacente era mala.
Me imagino que lo mismo será cierto para ti. Puede leer todo lo que quiera sobre el diseño y hacer lo mejor que pueda, pero se utilizará la prueba de ácido. Dedique algo de tiempo a desarrollar formas de obtener comentarios sobre lo que funciona y lo que no, y esté preparado para refactorizar según sea necesario para mejorarlo.
Una buena API es aquella que simplifica las cosas simples (mínimo estándar y curva de aprendizaje para hacer las cosas más comunes) y las cosas complicadas posibles (máxima flexibilidad, la menor cantidad posible de suposiciones). Una API mediocre es una que hace bien una de estas (ya sea increíblemente simple pero solo si está tratando de hacer cosas realmente básicas, o increíblemente poderosas, pero con una curva de aprendizaje realmente empinada, etc.). Una API horrible es una que no hace nada de esto bien.
Ya hay varias otras buenas respuestas sobre esto, así que pensé en agregar algunos enlaces que no vi mencionados.
Artículos
- " Un pequeño manual de diseño de API " por Jasmin Blanchette de Trolltech
- " Definición de las API QT-Style C ++ " también Trolltech
Libros:
Creo que una buena API debería permitir IO personalizados y ganchos de administración de memoria si es aplicable.
Un ejemplo típico es que tiene su formato de archivo comprimido personalizado para datos en el disco y una biblioteca de terceros con una API pobre quiere acceder a los datos en el disco y espera una ruta a un archivo donde pueda cargar sus datos.
Este enlace tiene algunos puntos buenos: http://gamearchitect.net/2008/09/19/good-middleware/
Si la API produce un mensaje de error, asegúrese de que el mensaje y los diagnósticos ayuden al desarrollador a resolver cuál es el problema.
Mi expectativa es que la persona que llama de una API pase la entrada correcta. Un desarrollador es el consumidor de cualquier mensaje de error producido por la API (no el usuario final), y los mensajes dirigidos al desarrollador ayudan al desarrollador a depurar su programa de llamadas.
Una API es mala cuando está mal documentada .
Una API es buena cuando está bien documentada y sigue un estándar de codificación .
Ahora, estos son dos puntos muy simples y también muy difíciles de seguir, esto lo lleva a uno al área de la arquitectura de software. Necesita un buen arquitecto que estructura el sistema y ayuda al marco a seguir sus propios lineamientos.
El código para comentar, escribir un manual bien explicado para la API es obligatorio.
Una API puede ser buena si tiene una buena documentación que explica cómo usarla. Pero si el código es limpio, bueno y sigue un estándar dentro de sí mismo, no importa si no tiene una documentación decente.
He escrito un poco sobre la estructura de codificación aquí
Creo que lo más importante es la legibilidad, con lo que me refiero a la calidad que hace que el mayor número de programadores tenga sentido de lo que está haciendo el código en el menor tiempo posible. Pero juzgar qué software es legible y cuál no tiene esa calidad humana indescriptible: la confusión. Los puntos que menciona en parte logran cristalizarlo. Sin embargo, en su totalidad tiene que seguir siendo un caso por caso y sería realmente difícil encontrar reglas universales.
