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?
Respuestas:
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.
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.
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.
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í.
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.
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.
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.
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.
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.
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.
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.
Asegúrese de agregar una licencia.
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.