Estou trabalhando em um projeto do Arduino usando o Uno. O projeto contém uma quantidade significativa de código. Gostaria de criar uma biblioteca e posso até compartilhá-la mais tarde. Quais diretrizes devo seguir ao projetar a biblioteca?
Respostas:
Há muitos pontos que você deve ter em mente ao criar uma biblioteca. Como você provavelmente acabará compartilhando seu trabalho com outras pessoas, é extremamente importante seguir padrões de design consistentes. Lembre-se de que outros usuários terão níveis de habilidade extremamente variados; portanto, crie uma biblioteca fácil de usar, na máxima extensão possível.
Forneça um mapa de pinos básico que sua biblioteca espera. Não mantenha o mapeamento de pinos estático, mas permita que o usuário faça alterações facilmente.
Uma das primeiras coisas que você deve tentar garantir é que sua biblioteca esteja funcionando. Se não estiver, declare claramente. Você não iria querer perder tempo tentando trabalhar com software quebrado, por isso não deixe que outros o façam também.
Mencione muito claramente em quais painéis a biblioteca foi projetada, em que foram testados e em quais painéis deve funcionar. Especifique a geração (versão) de cada placa mencionada aqui.
A próxima coisa é que você deve ter interfaces claramente definidas. Uma biblioteca de trabalho com interfaces complicadas é frustrante. Isso ajudará você a usar a biblioteca mais tarde e facilitará as coisas para outros usuários. Esse deve ser um dos aspectos mais importantes a serem lembrados.
Se você segue uma abordagem de cima para baixo ou de baixo para cima, as interfaces devem sempre estar claras em sua mente. Em uma abordagem de baixo para cima, isso pode e será difícil, mas não deve ser ignorado. Caso contrário, você terminará com uma biblioteca excessivamente complexa que pode não ser utilizável.
Se você tiver alguma função que utilize algumas características especiais da placa, certifique-se de destacar essas funções, mencione no leia-me e também nos comentários.
Pode haver cenários em que você precise usar uma espera ocupada. Tais funções, dependendo da lógica do programa, podem impedir o fluxo normal de controle, causando problemas enquanto estão no meio de uma tarefa crítica. Tente usar interrupções ou outros algoritmos, se possível. Caso contrário, mencione claramente marcar essas funções.
Continue comentando todas as pequenas e grandes mudanças que você fizer. Escreva bons comentários longos para todas as funções críticas e menores para outras. Descreva explicitamente sua interface, cada argumento, o que faz e o que retorna. Isso é muito trabalho extra, mas será imensamente útil para você e outras pessoas. Se você possui alguma função que pode não funcionar em placas diferentes, mencione-a aqui. Se essas são funções intermediárias usadas por outras funções e podem ser necessárias, mencione o Leia-me.
Verifique se tudo, até os comentários, são consistentes nos arquivos .he .cpp.
Mantenha apenas funções relacionadas em um único arquivo. Ter alguns módulos pequenos, mas logicamente consistentes, é melhor do que um arquivo enorme com tudo nele.
Escreva um arquivo leia-me claro que descreva a biblioteca, suas habilidades, quaisquer problemas ou bugs e usabilidade básica. Use um arquivo separado para definir e explicar cada interface, conforme descrito acima.
Depois que a biblioteca se tornar grande, é necessário dividi-la em diretórios. Isso não é facilmente possível ao usar o arduino-ide . Mas, se você chegou até aqui, provavelmente é um usuário avançado do Arduino e usa ferramentas de desenvolvimento mais poderosas. Caso contrário, este é o universo que está lhe dizendo para fazê-lo.
Certifique-se de adicionar uma licença.
Use uma ferramenta VCS como Git ou SVN. Isso tornará muito mais fácil ver as alterações feitas, reverter para versões antigas, detectar erros que causam códigos e até colaborar com outras pessoas.
A resposta do AshRj é muito boa - eu tenho apenas 2 pontos a acrescentar.
Ponto 1: Documentação
AshRj recomendou escrever um leia-me detalhado. Embora isso possa ser uma boa prática, pode rapidamente ficar fora de controle com bibliotecas maiores - de fato, mesmo em algumas milhares de linhas (o que realmente não é muito), um leia-me quase não terá benefícios. Minha recomendação seria ir um passo adiante e usar o equivalente de Javadocs para C ++ - como esta resposta explica (está no Stack Overflow), o Doxygen é uma ferramenta muito útil para manter a documentação gerenciável e à mão (ninguém deseja editar um Arquivo leia-me de 10 mil linhas ...)
Ponto 2: Diretórios
Novamente contrastando com a resposta do AshRj, sempre use diretórios. Mesmo se você tiver apenas 10 arquivos, talvez apenas com 7 ou 8. Sei que parece um pouco estúpido, mas é um trabalho para o futuro, e se você não começar cedo, acabará com uma bagunça arquivos. Os diretórios não são apenas para projetos grandes - os pequenos também devem usá-los. Lembre-se de que no C ++ (a linguagem de fato Arduino), os diretórios são ignorados ao incluir arquivos de uma biblioteca - eles existem apenas como uma ferramenta de gerenciamento de código.