Estoy trabajando en un proyecto Arduino usando el Uno. El proyecto contiene una cantidad significativa de código. Me gustaría crear una biblioteca e incluso podría compartirla más adelante. ¿Qué pautas debo seguir al diseñar la biblioteca?

Hay muchos puntos que debe tener en cuenta al diseñar una biblioteca. Como probablemente terminará compartiendo su trabajo con otros, es extremadamente importante seguir patrones de diseño consistentes. Tenga en cuenta que otros usuarios tendrán niveles de habilidad extremadamente variables, por lo tanto, diseñe una biblioteca fácil de usar, en la mayor medida posible.

Consejos básicos

Mapa de pin

Proporcione un mapa de pin básico que su biblioteca está esperando. No mantenga la asignación de pines estática, pero permita que el usuario realice cambios fácilmente.

Biblioteca de trabajo

Una de las primeras cosas que debe intentar asegurarse es que su biblioteca esté funcionando. Si no es así, dígalo claramente. No querrás terminar perdiendo el tiempo tratando de trabajar con software dañado, así que no dejes que otros también lo hagan.

Léame básico

Mencione claramente para qué placa (s) se diseñó la biblioteca, en qué se probó y qué placa (s) se espera que funcione. Especifique la generación (versión) de cada placa mencionada aquí.

Interfaces

Lo siguiente es que debe tener interfaces claramente definidas. Una biblioteca de trabajo con interfaces enrevesadas es frustrante. Esto lo ayudará a usar la biblioteca más adelante y facilitará las cosas a otros usuarios. Este debería ser uno de los aspectos más importantes a tener en cuenta.

Ya sea que siga un enfoque de arriba hacia abajo o de abajo hacia arriba, las interfaces siempre deben estar claras en su mente. En un enfoque de abajo hacia arriba, esto puede y será difícil, pero no debe ignorarse. De lo contrario, terminará con una biblioteca demasiado compleja que puede no ser utilizable.

Funciones especiales

Si tiene alguna función que use algunas características especiales de la placa, asegúrese de hacer que estas funciones se destaquen, mencione en el archivo Léame y también en los comentarios.

Esperas ocupadas

Puede haber escenarios en los que deba usar una espera ocupada. Dichas funciones, dependiendo de la lógica del programa, pueden evitar el flujo de control normal, causando problemas en medio de una tarea crítica. Intente utilizar interrupciones u otros algoritmos, si es posible. Si no, entonces mencione claramente marcar cualquiera de esas funciones.

Comentarios

Asegúrese de seguir comentando cada pequeño y gran cambio que realice. Escriba comentarios largos y agradables para todas las funciones críticas y otras más pequeñas para otros. Describa explícitamente su interfaz, cada argumento, lo que hace y lo que devuelve. Esto es mucho trabajo extra, pero será inmensamente útil tanto para usted como para los demás. Si tiene alguna función que puede no funcionar en diferentes placas, mencione aquí. Si estas son funciones intermedias utilizadas por otras funciones y pueden ser necesarias, mencione en el archivo Léame.

Consistencia

Asegúrese de que todo, incluso los comentarios, sean coherentes entre los archivos .hy .cpp.

Mantenga solo las funciones relacionadas dentro de un solo archivo. Tener algunos módulos pequeños, pero lógicamente consistentes, es mejor que un archivo enorme con todo lo que contiene.

Consejos avanzados

Léame detallado

Escriba un archivo léame claro que describa la biblioteca, sus capacidades, cualquier problema o error y la facilidad de uso básica. Use un archivo separado para definir y explicar cada interfaz como se describe anteriormente.

Estructura de directorios

Una vez que la biblioteca se vuelve grande, puede ser necesario dividirla en directorios. Esto no es fácilmente posible mientras se usa el arduino-ide . Pero, si llegó hasta aquí, probablemente sea un usuario avanzado de Arduino y use herramientas de desarrollo más potentes. Si no, este es el universo que te dice que lo hagas.

Licencia

Asegúrese de agregar una licencia.

Control de versiones

Use una herramienta VCS como Git o SVN. Esto hará que sea mucho más fácil ver los cambios realizados, volver a las versiones anteriores, detectar códigos que causan errores e incluso colaborar con otros.

La respuesta de AshRj es muy buena: solo tengo 2 puntos para agregar.

Punto 1: Documentación

AshRj recomendó escribir un archivo Léame detallado. Si bien esto puede ser una buena práctica, puede salirse rápidamente de control con las bibliotecas más grandes; de hecho, incluso con unos pocos miles de líneas (que en realidad no es mucho), un archivo Léame casi no tendrá ningún beneficio. Mi recomendación sería ir un paso más allá y usar el equivalente de Javadocs para C ++; como explica esta respuesta (está en Stack Overflow), Doxygen es una herramienta muy útil para mantener la documentación manejable y a mano (nadie quiere editar un Archivo Léame de 10K líneas ...)

Punto 2: Directorios

Nuevamente contrastando con la respuesta de AshRj, siempre use directorios. Incluso si solo tiene 10 archivos, tal vez incluso con solo 7 u 8. Sé que suena un poco estúpido, pero está preparando su trabajo para el futuro, y si no comienza temprano, terminará con un desastre. archivos. Los directorios no son solo para proyectos grandes, los pequeños también deberían usarlos. Solo recuerde que en C ++ (el lenguaje de facto Arduino), los directorios se ignoran cuando se incluyen archivos de una biblioteca; existen solo como una herramienta de administración de código.