Ich arbeite an einem Arduino-Projekt mit dem Uno. Das Projekt enthält eine erhebliche Menge an Code. Ich möchte eine Bibliothek erstellen und kann sie später sogar teilen. Welche Richtlinien sollte ich beim Entwerfen der Bibliothek beachten?
Antworten:
Es gibt viele Punkte, die Sie beim Entwerfen einer Bibliothek beachten sollten. Wie Sie wahrscheinlich am Ende Ihre Arbeit mit anderen teilen werden, ist es äußerst wichtig, konsistente Entwurfsmuster zu befolgen. Denken Sie daran, dass andere Benutzer sehr unterschiedliche Fähigkeiten haben. Entwerfen Sie daher eine benutzerfreundliche Bibliothek, so weit wie möglich.
Stellen Sie eine grundlegende Pin-Map bereit, die Ihre Bibliothek erwartet. Halten Sie die Pin-Zuordnung nicht statisch, sondern lassen Sie den Benutzer problemlos Änderungen vornehmen.
Eines der ersten Dinge, die Sie sicherstellen sollten, ist, dass Ihre Bibliothek funktioniert. Wenn nicht, geben Sie dies eindeutig an. Sie möchten nicht Ihre Zeit damit verschwenden, mit defekter Software zu arbeiten. Lassen Sie dies also nicht auch andere tun.
Erwähnen Sie sehr deutlich, für welche Platine (n) die Bibliothek entworfen wurde, auf welcher sie getestet wurde und für welche Platine (n) sie voraussichtlich funktionieren wird. Geben Sie die Generation (Version) jeder hier genannten Karte an.
Als nächstes sollten Sie klar definierte Schnittstellen haben. Eine Arbeitsbibliothek mit verschlungenen Schnittstellen ist frustrierend. Dies hilft Ihnen, die Bibliothek später selbst zu verwenden, und erleichtert anderen Benutzern die Arbeit. Dies sollte einer der wichtigsten Aspekte sein, die berücksichtigt werden müssen.
Unabhängig davon, ob Sie einen Top-Down- oder einen Bottom-Up-Ansatz verfolgen, sollten die Schnittstellen immer klar im Kopf sein. Bei einem Bottom-up-Ansatz kann und wird dies schwierig sein, sollte jedoch nicht ignoriert werden. Andernfalls erhalten Sie eine übermäßig komplexe Bibliothek, die möglicherweise nicht verwendet werden kann.
Wenn Sie Funktionen haben, die bestimmte Board-Eigenschaften verwenden, stellen Sie sicher, dass diese Funktionen hervorstechen. Erwähnen Sie dies in der Readme-Datei und auch in den Kommentaren.
Es kann Szenarien geben, in denen Sie möglicherweise viel warten müssen. Solche Funktionen können abhängig von der Programmlogik einen normalen Steuerungsfluss verhindern und somit Probleme verursachen, während sie sich mitten in einer kritischen Aufgabe befinden. Versuchen Sie nach Möglichkeit, Interrupts oder andere Algorithmen zu verwenden. Wenn nicht, erwähnen Sie diese Funktionen deutlich.
Stellen Sie sicher, dass Sie jede kleine und große Änderung, die Sie vornehmen, kommentieren. Schreiben Sie schöne lange Kommentare für alle kritischen Funktionen und kleinere für andere. Beschreiben Sie explizit Ihre Schnittstelle, jedes Argument, was es tut und was es zurückgibt. Dies ist eine Menge zusätzlicher Arbeit, die jedoch sowohl für Sie als auch für andere sehr hilfreich sein wird. Wenn Sie Funktionen haben, die möglicherweise nicht auf verschiedenen Karten funktionieren, erwähnen Sie diese hier. Wenn dies Zwischenfunktionen sind, die von anderen Funktionen verwendet werden und möglicherweise erforderlich sind, erwähnen Sie dies in der Readme-Datei.
Stellen Sie sicher , alles, auch die Kommentare sind konsistent über die .hund .cppDateien.
Behalten Sie nur verwandte Funktionen in einer einzigen Datei. Ein paar kleine, aber logisch konsistente Module sind besser als eine große Datei mit allem, was darin enthalten ist.
Schreiben Sie eine übersichtliche Readme-Datei, in der die Bibliothek, ihre Fähigkeiten, Probleme oder Fehler sowie die grundlegende Benutzerfreundlichkeit beschrieben werden. Verwenden Sie eine separate Datei, um jede Schnittstelle wie oben beschrieben zu definieren und zu erklären.
Sobald die Bibliothek groß wird, kann es erforderlich sein, sie in Verzeichnisse zu unterteilen. Dies ist mit dem Arduino-Ide nicht einfach möglich . Wenn Sie jedoch so weit gekommen sind, sind Sie wahrscheinlich ein fortgeschrittener Arduino-Benutzer und verwenden leistungsfähigere Entwicklungstools. Wenn nicht, ist dies das Universum, das Sie dazu auffordert.
Stellen Sie sicher, dass Sie eine Lizenz hinzufügen.
Verwenden Sie ein VCS-Tool wie Git oder SVN. Dies macht es viel einfacher, vorgenommene Änderungen zu sehen, auf alte Versionen zurückzugreifen, Fehler zu erkennen, die Code verursachen, und sogar mit anderen zusammenzuarbeiten.
Die Antwort von AshRj ist sehr gut - ich habe nur 2 Punkte hinzuzufügen.
Punkt 1: Dokumentation
AshRj empfahl, eine detaillierte Readme-Datei zu schreiben. Dies kann zwar eine gute Vorgehensweise sein, bei größeren Bibliotheken jedoch schnell außer Kontrolle geraten - selbst bei einigen tausend Zeilen (was eigentlich nicht viel ist) hat eine Readme-Datei fast keinen Nutzen. Meine Empfehlung wäre, noch einen Schritt weiter zu gehen und das Äquivalent von Javadocs für C ++ zu verwenden - wie diese Antwort erklärt (es handelt sich um einen Stapelüberlauf ), ist Doxygen ein sehr nützliches Werkzeug, um die Dokumentation überschaubar und griffbereit zu halten (niemand möchte a bearbeiten) 10K-Zeilen-Readme-Datei ...)
Punkt 2: Verzeichnisse
Verwenden Sie im Gegensatz zu AshRjs Antwort immer Verzeichnisse. Selbst wenn Sie nur 10 Dateien haben, vielleicht sogar mit nur 7 oder 8. Ich weiß, dass es ein bisschen dumm klingt, aber es ist zukunftssicher für Ihre Arbeit, und wenn Sie nicht früh anfangen, werden Sie nur ein Durcheinander von Dateien. Verzeichnisse sind nicht nur für große Projekte gedacht - auch kleine sollten sie verwenden. Denken Sie daran, dass in C ++ (der De-facto-Arduino-Sprache) Verzeichnisse beim Einschließen von Dateien aus einer Bibliothek ignoriert werden - sie existieren nur als Code-Management-Tool.