¿Qué debo tener en cuenta para diseñar una interfaz SDK?

Answer 1

Varía dependiendo de exactamente lo que está construyendo, pero aquí hay algunas cosas que siempre tendrá que considerar:

• Enlaces de idiomas: ¿desde qué idiomas desea que se pueda acceder a su SDK? Los enlaces para varios idiomas tienen algunas reglas y limitaciones. Debe investigar esto y comprenderlo antes de diseñar su interfaz.
• Facilidad de uso: parece obvio, pero siempre vale la pena indicarlo. Debe intentar transmitir el problema que su SDK resuelve de una manera intuitiva que reduce la curva de aprendizaje tanto como sea posible.
• Documentación: ¿cómo administrará la documentación de su interfaz SDK?
• Gestión de memoria / objeto: específicamente con respecto a los objetos o la memoria que fluyen a través de la interfaz SDK. Considere (a veces caso por caso) cómo interactuarán los datos y los objetos. ¿Se interactuará atómicamente mediante llamadas a métodos? ¿O el cliente obtendrá acceso permanente o temporal a los datos u objetos? Si este último, ¿quién tiene el control de su vida? ¿Es necesario devolver el objeto o los datos al SDK o simplemente se puede destruir? También todas esas mismas preguntas para datos u objetos que el cliente proporcionará al SDK. Si usa o no un lenguaje recolectado de basura afectará la importancia, y ciertamente al menos su enfoque, a estas preguntas.
• Facilidad de pruebas de automatización. ¿Planea automatizar las pruebas de su SDK? Hay muchas opiniones sobre las pruebas automatizadas, que van desde “es inútil, no lo hagas” hasta “¡todo lo que necesito hacer es codificar 9 millones de pruebas unitarias y luego ya no necesito un equipo de control de calidad!” SDK tiene algunas pruebas automatizadas, debe diseñar para ello. Es sorprendentemente fácil diseñar un sistema que funcione muy bien, pero adaptarlo con pruebas más adelante es una pesadilla.

Una nota sobre el tema de “desarrollo basado en pruebas”: he visto equipos disparar y generar interfaces enteras y codificar grandes cantidades de pruebas unitarias antes de que alguna vez funcionen. No es de extrañar que piensen que el desarrollo impulsado por pruebas es terrible. Acaban de pasar una eternidad codificando un montón de pruebas, la mayoría de las cuales se reescribirán cuando descubran que su enfoque de interfaz era deficiente a la mitad del proyecto.

Escriba una llamada, es una prueba y luego su implementación (en ese orden) una llamada a la vez. Creo firmemente en esto, especialmente para las interfaces SDK. Dos razones: 1) la codificación de la prueba primero hace que sea imposible diseñar su interfaz sin consideraciones para una prueba fácil. 2) codificar la prueba primero lo obliga a ser un usuario de su interfaz , antes de convertirse en un diseñador de su interfaz . Cuando adopté esta práctica, me resultó difícil y costoso al principio. Con la práctica, sucedieron dos cosas: me puse más rápido y noté que el diseño de mi interfaz mejoró significativamente. Tenga en cuenta que definitivamente NO le estoy animando a que codifique todos los casos posibles de cada llamada posible en las pruebas unitarias antes de implementar. No soy fanático del código de prueba de unidades hasta la muerte. Las pruebas unitarias no son una herramienta de control de calidad. He tenido discusiones interminables con los gerentes que pensaban que las pruebas unitarias equivalían a una evaluación de control de calidad válida, por lo que pensaron que un número suficientemente alto de pruebas unitarias nos permitía renunciar a otros tipos de control de calidad. ¡INCORRECTO! Las pruebas unitarias son una herramienta de desarrollo. Ayudan a demostrar y documentar las principales características. Codifican y aclaran las interfaces públicas. Se aseguran de que otras personas que luego trabajen en su código tengan una red de seguridad contra las funciones básicas de ruptura mientras aprenden o corrigen pequeños errores en áreas desconocidas. Codifique las pruebas que lo ayudan a desarrollarse. Las pruebas unitarias son de baja calidad. Para codificar suficientes pruebas unitarias para cubrir completamente todos los casos de todas sus interfaces, es probable que termine con varias veces más código de prueba unitaria que el código de implementación real. Si está codificando un SDK que tiene 100,000 líneas de código, ¿es realmente práctico, eficiente o útil codificar 400,000 líneas de prueba unitaria? Y aún no me he metido en la idea de que las pruebas unitarias solo prueban las unidades, y no la integración, que es donde ocurren la mayoría de los errores.

Dos notas especiales si está trabajando en C ++.

1. Tenga mucho cuidado si su interfaz manejará cadenas internacionalizadas. El manejo de cadenas C / C ++ es un campo minado. Es tan antiguo que está plagado de evidencia de soluciones pasadas a cadenas internacionales. Intentos que parecían buenos en ese momento, y luego fracasaron en la práctica. Hay muchas maneras de manejar cadenas en C / C ++ o dentro de la API del sistema operativo (mirando sus ventanas …) que parecen oficiales y recomendadas, pero ya no se recomiendan. Permanecen porque no tienen reemplazo. El método adecuado, aunque ahora se acordó casi universalmente, simplemente todavía no se había incorporado completamente al idioma. Si necesita hacer esto, mi consejo es que se adhiera completamente a UTF-8. Use una biblioteca que pueda proporcionar algoritmos de cadena seguros UTF-8. Use la UCI si necesita servicios de texto completo. Use Utfcpp si solo necesita un almacenamiento liviano y algos básicos. Si solo necesita almacenamiento, puede usar std :: string, pero tenga en cuenta que algunas funciones de modificación y búsqueda harán lo incorrecto.
2. Si su interfaz SDK podría ser la interfaz de un objeto compartido en algún momento, no use C ++ para su interfaz. Puede usar C ++ para la implementación interna, pero para la interfaz pública debe reducirlo a C y usar la “C” externa. La razón es que el ABI de C ++ y, por lo tanto, el enlace del lenguaje, están fundamentalmente rotos y tienen un conjunto de reglas bastante desagradable y difícil de manejar que deben seguirse para evitar estragos. Nuevamente, la solución está llegando pero aún está en desarrollo. En este caso, vea “módulos” C ++. Todavía es altamente experimental y solo es compatible con la vanguardia del sonido y el estudio visual. Si eso no te asusta, no dudes en usarlo, ciertamente es el camino del futuro para las interfaces C ++. Fuera de esta nueva característica, solo he visto dos tratamientos verdaderamente apropiados de objetos en las interfaces de C ++: Qt y COM, los cuales lo logran efectivamente al escribir un enlace de envoltura que evita en gran medida los enlaces rotos de C ++.

Una publicación especialmente larga aquí, pero oye, preguntaste sobre un tema bastante carnoso …