¿Qué tienen en común las grandes API? [cerrado]

¿Qué tienen las API geniales que las hace geniales? Creo que adherirse al mantra "haz una cosa y hazlo bien" es una buena señal y ser un buen mapeo del dominio del problema es importante, pero ¿qué tienen en común las grandes API?

Debes tener cuidado de evitar agregar vocabulario nuevo solo por tu API. Mis API favoritas me explican cosas en vocabulario que ya entiendo. Entre esas líneas:

No agregue demasiadas abstracciones sobre lo que está construyendo. Mantenlo simple.

Ya tengo que pensar en media docena de capas de abstracción. No me hagas pensar en capas adicionales. No me des muchas cosas nuevas para aprender que no agreguen valor a mi objetivo final. Por ejemplo, evite usar su propia clase de archivo especial que funcione de manera diferente que el tipo de archivo del idioma solo porque cree que su forma es mejor que la forma generalmente aceptada. Quédese con la forma generalmente aceptada, al menos en sus interfaces, para bien o para mal.

Seguir con ideas concretas

Por ejemplo, no intente ocultar el hecho de que la parte "modelo" de su marco MVC es una interfaz para una base de datos. Aproveche el vocabulario bien conocido que rodea a las "bases de datos". Sé lo que son las claves foráneas. Sé lo que son las filas y columnas. Háblame en estos términos.

No abstraiga el conocimiento esencial.

Similar a trabajar con ideas concretas. No oculte el hecho de que estamos tratando con archivos o bases de datos o filas en bases de datos. Yo se estas cosas. Si estoy tratando con un contenedor, como una Lista, hay una buena posibilidad de que necesite conocer la complejidad algorítmica de las operaciones comunes. Puede simplificar mucho eso simplemente diciéndome que es una "lista vinculada" o una "matriz". De repente, un gran conjunto de ideas se aplicará a lo que estás haciendo y de repente todo tendrá sentido. No cree su propio conjunto de ideas que tengo que aprender cuando ya venga con un conjunto rico y útil de terminología para aplicar al problema.

Reduce la cantidad de términos que necesito en mi vocabulario

Si estoy usando su API para abrir un archivo de imagen de cualquier tipo, no debería tener que pensar mucho en pngs vs gifs vs jpgs. Harás eso por mí. Es tu competencia principal, no la mía. Tengo una vaga comprensión de que tienes algo de magia para hacer esto por mí.

Una API útil tiene lo siguiente:

• Documentación concisa y exhaustiva. Si estoy buscando cómo implementar una tarea, puedo averiguar si la API tiene la capacidad de hacerlo, en un par de minutos. Esto se logra por la brevedad del texto y el diseño del recurso. La documentación proporciona ejemplos sobre cómo usarlo y tampoco hace suposiciones sobre los lectores.
• Una comunidad grande y activa. Estoy emocionado cuando encuentro foros, canales IRC, listas de correo, etc. con participantes activos dispuestos a ayudar a los nuevos muchachos. Entiendo que este suele ser el caso para proyectos más grandes, pero aún así, sería algo por lo que luchar.
• Consistencia. Cuando realmente estoy usando la API, no quiero sorprenderme de ninguna manera cuando llamo a un método, o descubro que ese método Xes completamente diferente de la convención establecida por el resto de la API.

Grandes API tienen una excelente documentación.

• Haz una cosa y hazlo genial.
• Fácil de usar, difícil de usar mal.
• Fácil de extender.
• Bien documentada.
• Estilo consistente

Jaroslav Tulach, del equipo de NetBeans, aborda esta pregunta en "Diseño práctico de API: Confesiones de un arquitecto de estructuras Java".

La interfaz útil más simple y buenas convenciones de nomenclatura.