¿Cuándo se sobreinyecta una API?

Question

No me gusta trabajar con API sobreescritas que no simplifican las cosas simples. No obstante, estoy trabajando en el diseño de una API para una biblioteca de código abierto y estoy empezando a sentir que estoy cayendo en la trampa de la sobreingeniería. Realmente no puedo asegurarlo porque, por supuesto, escribí una maldita cosa, así que cómo funciona es más obvio para mí que nadie. ¿Cuáles son algunas señales de advertencia desde la perspectiva de un desarrollador de que su API podría ser sobreinjertada?

Answer 1

"¿Cuáles son algunas señales de advertencia desde el punto de vista de un desarrollador de que su API podría sobreestimarse?"

Sin casos de uso.

Si no puede ejecutar los escenarios simples de "hacerlo", no está diseñando una API útil con casos de uso específicos en mente.

Su documentación debe ser esos casos de uso.

Las características que no abordan directamente los casos de uso probablemente sean exceso de ingeniería.

Answer 2

Dos (relacionados) preguntas que debe hacerse inmediatamente vienen a la mente:

• ¿Hay cosas que se pueden hacer en más de una forma?
• ¿Hay métodos/propiedades en la API que se puedan expresar en términos del resto de la API?

más difícil de responder, y no una señal de manipulación excesiva en sí mismo, pero sin duda un signo de que la API no es tan simple como podría ser aún:

• ¿Hay otros métodos/propiedades que se puede introducir que permitiría eliminar más de lo que introdujo (basado en las otras dos preguntas)

Answer 3

Al revisar la documentación y los ejemplos, el porcentaje de verborrea que discutía la API en relación con ella misma se concentró en el porcentaje de verborrea que discutía su aplicación a casos de uso creíbles.

Answer 4

Como dijo S.Lott, use-cases. Ellos determinarán a qué exactamente debe dirigirse su API. Si diseñas tu API para completar un objetivo muy claro y específico: functionally coherent, lo más probable es que termines con una API o componente en tu API que sea fácil de usar y comprender.

Diseñar una API debería ser como diseñar una interfaz de usuario. La mayoría de los conceptos de IU pueden ser adoptados por una API, por ejemplo, el principio KISS o incluso Kaizen.

Tendría un enlace a esos conceptos de UI, pero soy un nuevo usuario por lo que no me dejan publicar más de 1 hipervínculo. Buen ejemplo allí: StackOverflow, avísanos antes de publicar;).

Answer 5

Deberías echarle un vistazo a Google Tech Talk How To Design A Good API and Why it Matters de Joshua Bloch ... él cubre muchas de estas cosas.

Answer 6

Cuando es tan inteligente que nadie más puede entenderlo.

Answer 7

cuando el seguimiento de la pila para una llamada de API común requiere que se desplace la pantalla para ver todo el asunto.

Answer 8

Comience a preocuparse cuando tenga una API grande con muchas funciones que, en una inspección más cercana, resultan ser composiciones de operaciones más simples. Una API con una alta proporción de mecanismos de composición a primitivos suele ser un buen diseño.

(diseño API es muy similar al diseño del lenguaje, y aquí estoy esencialmente abrazar la filosofía Esquema — en lugar de acumular más rutinas en el API, simplificar e incluir mecanismos de composición que hacen las rutinas adicionales innecesarios.)

Answer 9

Un truco que encontré muy útil y me ha ayudado en el pasado es escribir doc antes, durante y después de codificar.

Al diseñar una API para ser utilizada por otras personas, normalmente documento el diseño antes de escribir el código. Si estaba sobreingeniendo el diseño, las especificaciones de diseño generalmente están llenas de conflictos y tonterías.

Durante la codificación, usualmente resuelvo la definición de clase y el cuerpo de la función y comienzo a escribir los comentarios de doxygen para ellos. En los comentarios tendré caso de uso, código de muestra y suposiciones de las interfaces. Durante esta fase, antes de que se escriba demasiado código real, la interfaz de la clase generalmente se rediseña varias veces. Sé que estaba sobreingeniería cuando el código de muestra es difícil de escribir y me es difícil explicar la interfaz. Muchas de las ideas de diseño incorrectas se exponen y eliminan cuando intentas explicarle a la gente cómo usar tu API.

Después de la codificación, reemplazo el código de muestra en los comentarios con código real compilado y probado copiado de mis pruebas unitarias y documentando además el comportamiento de la interfaz. Otro signo de sobreingeniería es cuando mis pruebas de unidad no pueden seguir el cambio de interfaz porque hay demasiadas partes móviles y demasiadas formas de hacer lo mismo y la unidad prueba el crecimiento en una proporción exponencial.

Answer 10

Cuando se usa el API es: (1) más obtuso, más complejo, menos eficiente, y menos predecible que simplemente usando la tecnología subyacente, Y (2) no ofrece una ventaja significativa para la seguridad, la escalabilidad, o libertad multiplataforma.

Answer 11

Según mi experiencia, puede ver cuándo se demora todo el proyecto durante meses, esperando a que la API finalice.