Jakich wskazówek należy przestrzegać podczas projektowania biblioteki?
11
Pracuję nad projektem Arduino za pomocą Uno. Projekt zawiera znaczną ilość kodu. Chciałbym stworzyć bibliotekę i mogę ją nawet udostępnić później. Jakich wskazówek należy przestrzegać podczas projektowania biblioteki?
Czy nie jest to bardziej ogólne pytanie, być może w przypadku Przepełnienia stosu - wydaje się, że część Arduino jest w tym przypadku nieistotna. To powiedziawszy, może dostarczyć użytecznych wskazówek dotyczących ograniczeń pamięci Arduino.
Odpowiedzi:
12
Jest wiele kwestii, o których należy pamiętać przy projektowaniu biblioteki. Jak zapewne skończysz, dzieląc się swoją pracą z innymi, niezwykle ważne jest przestrzeganie spójnych wzorców projektowych. Pamiętaj, że inni użytkownicy będą mieli bardzo różne poziomy umiejętności, więc zaprojektuj łatwą w użyciu bibliotekę w maksymalnym możliwym zakresie.
Podstawowe wskazówki
Mapa pinów
Podaj podstawową mapę pinów, której oczekuje Twoja biblioteka. Nie należy utrzymywać statycznego mapowania pinów, ale umożliwia użytkownikowi łatwe wprowadzanie zmian.
Biblioteka robocza
Jedną z pierwszych rzeczy, które powinieneś upewnić się, jest to, że twoja biblioteka działa. Jeśli nie, wyraźnie to zaznacz. Nie chcesz marnować czasu na pracę z uszkodzonym oprogramowaniem, więc nie pozwól, aby inni też to zrobili.
Podstawowy plik Readme
Wymień bardzo wyraźnie, dla których płyt (y) biblioteka została zaprojektowana, na których została przetestowana i na jakich tablicach ma działać. Określ generację (wersję) każdej płyty wymienionej tutaj.
Interfejsy
Następną rzeczą jest to, że powinieneś mieć jasno zdefiniowane interfejsy. Działająca biblioteka z zawiłymi interfejsami jest frustrująca. Pomoże Ci to później korzystać z biblioteki i ułatwi innym użytkownikom. Powinno to być jednym z najważniejszych aspektów, o których należy pamiętać.
Niezależnie od tego, czy stosujesz podejście odgórne, czy oddolne, interfejsy powinny zawsze mieć na uwadze. W podejściu oddolnym może to i będzie trudne, ale nie należy tego ignorować. W przeciwnym razie powstanie zbyt skomplikowana biblioteka, która może nie być użyteczna.
Funkcje specjalne
Jeśli masz jakieś funkcje, które wykorzystują pewne specjalne cechy płyty, upewnij się, że wyróżniają się one, o czym wspomnij w pliku readme, a także w komentarzach.
Zajęty
Mogą istnieć scenariusze, w których możesz potrzebować zajętego oczekiwania. Takie funkcje, w zależności od logiki programu, mogą uniemożliwić normalny przepływ sterowania, powodując problemy podczas wykonywania zadania o znaczeniu krytycznym. Spróbuj użyć przerwań lub innych algorytmów, jeśli to możliwe. Jeśli nie, to wyraźnie zaznacz wszelkie takie funkcje.
Komentarze
Pamiętaj o komentowaniu każdej wprowadzonej małej i dużej zmiany. Napisz miłe długie komentarze do wszystkich najważniejszych funkcji, a mniejsze do innych. Wyraźnie opisz swój interfejs, każdy argument, co robi i co zwraca. To dużo dodatkowej pracy, ale będzie niezwykle pomocne zarówno dla ciebie, jak i dla innych. Jeśli masz jakieś funkcje, które mogą nie działać na różnych tablicach, wspomnij o tym tutaj. Jeśli są to funkcje pośrednie używane przez inne funkcje i mogą być konieczne, należy wspomnieć w pliku Readme.
Konsystencja
Upewnij się, że wszystko, nawet komentarze, są spójne w plikach .hi .cpp.
Zachowaj tylko powiązane funkcje w jednym pliku. Posiadanie kilku małych, ale logicznie spójnych modułów jest lepsze niż jeden ogromny plik z zawartością.
Zaawansowane porady
Szczegółowy plik Readme
Napisz przejrzysty plik readme opisujący bibliotekę, jej możliwości, problemy i błędy oraz podstawową użyteczność. Użyj osobnego pliku do zdefiniowania i wyjaśnienia każdego interfejsu, jak opisano powyżej.
Struktura katalogów
Gdy biblioteka stanie się duża, konieczne może być podzielenie jej na katalogi. Nie jest to łatwo możliwe przy użyciu arduino-ide . Ale jeśli doszedłeś tak daleko, prawdopodobnie jesteś zaawansowanym użytkownikiem Arduino i korzystasz z bardziej zaawansowanych narzędzi programistycznych. Jeśli nie, to wszechświat każe ci to zrobić.
Koncesjonowanie
Pamiętaj, aby dodać licencję.
Kontrola wersji
Użyj narzędzia VCS, takiego jak Git lub SVN. Ułatwi to zobaczenie wprowadzonych zmian, powrót do starych wersji, wykrycie błędu powodującego błąd, a nawet współpracę z innymi.
Odpowiedź AshRj jest bardzo dobra - mam tylko 2 punkty do dodania.
Punkt 1: Dokumentacja
AshRj zalecił napisanie szczegółowego pliku Readme. Chociaż może to być dobra praktyka, może szybko wymknąć się spod kontroli z większymi bibliotekami - w rzeczywistości nawet przy kilku tysiącach wierszy (co jest naprawdę niewiele), readme nie przyniesie prawie żadnych korzyści. Polecam pójść o krok dalej i użyć odpowiednika Javadocs dla C ++ - jak wyjaśnia ta odpowiedź (dotyczy przepełnienia stosu), Doxygen jest bardzo przydatnym narzędziem do zarządzania dokumentacją i zarządzania nią (nikt nie chce edytować Plik readme o rozmiarze 10 KB ...)
Punkt 2: Katalogi
Ponownie, w przeciwieństwie do odpowiedzi AshRj, zawsze używaj katalogów. Nawet jeśli masz tylko 10 plików, może nawet 7 lub 8. Wiem, że to brzmi trochę głupio, ale to zabezpiecza twoją przyszłość na przyszłość, a jeśli nie zaczniesz wcześnie, po prostu skończy się bałagan akta. Katalogi nie są przeznaczone tylko do dużych projektów - również małe powinny z nich korzystać. Pamiętaj tylko, że w C ++ (de facto język Arduino) katalogi są ignorowane przy dołączaniu plików z biblioteki - istnieją tylko jako narzędzie do zarządzania kodami.
Odpowiedzi:
Jest wiele kwestii, o których należy pamiętać przy projektowaniu biblioteki. Jak zapewne skończysz, dzieląc się swoją pracą z innymi, niezwykle ważne jest przestrzeganie spójnych wzorców projektowych. Pamiętaj, że inni użytkownicy będą mieli bardzo różne poziomy umiejętności, więc zaprojektuj łatwą w użyciu bibliotekę w maksymalnym możliwym zakresie.
Podstawowe wskazówki
Mapa pinów
Podaj podstawową mapę pinów, której oczekuje Twoja biblioteka. Nie należy utrzymywać statycznego mapowania pinów, ale umożliwia użytkownikowi łatwe wprowadzanie zmian.
Biblioteka robocza
Jedną z pierwszych rzeczy, które powinieneś upewnić się, jest to, że twoja biblioteka działa. Jeśli nie, wyraźnie to zaznacz. Nie chcesz marnować czasu na pracę z uszkodzonym oprogramowaniem, więc nie pozwól, aby inni też to zrobili.
Podstawowy plik Readme
Wymień bardzo wyraźnie, dla których płyt (y) biblioteka została zaprojektowana, na których została przetestowana i na jakich tablicach ma działać. Określ generację (wersję) każdej płyty wymienionej tutaj.
Interfejsy
Następną rzeczą jest to, że powinieneś mieć jasno zdefiniowane interfejsy. Działająca biblioteka z zawiłymi interfejsami jest frustrująca. Pomoże Ci to później korzystać z biblioteki i ułatwi innym użytkownikom. Powinno to być jednym z najważniejszych aspektów, o których należy pamiętać.
Niezależnie od tego, czy stosujesz podejście odgórne, czy oddolne, interfejsy powinny zawsze mieć na uwadze. W podejściu oddolnym może to i będzie trudne, ale nie należy tego ignorować. W przeciwnym razie powstanie zbyt skomplikowana biblioteka, która może nie być użyteczna.
Funkcje specjalne
Jeśli masz jakieś funkcje, które wykorzystują pewne specjalne cechy płyty, upewnij się, że wyróżniają się one, o czym wspomnij w pliku readme, a także w komentarzach.
Zajęty
Mogą istnieć scenariusze, w których możesz potrzebować zajętego oczekiwania. Takie funkcje, w zależności od logiki programu, mogą uniemożliwić normalny przepływ sterowania, powodując problemy podczas wykonywania zadania o znaczeniu krytycznym. Spróbuj użyć przerwań lub innych algorytmów, jeśli to możliwe. Jeśli nie, to wyraźnie zaznacz wszelkie takie funkcje.
Komentarze
Pamiętaj o komentowaniu każdej wprowadzonej małej i dużej zmiany. Napisz miłe długie komentarze do wszystkich najważniejszych funkcji, a mniejsze do innych. Wyraźnie opisz swój interfejs, każdy argument, co robi i co zwraca. To dużo dodatkowej pracy, ale będzie niezwykle pomocne zarówno dla ciebie, jak i dla innych. Jeśli masz jakieś funkcje, które mogą nie działać na różnych tablicach, wspomnij o tym tutaj. Jeśli są to funkcje pośrednie używane przez inne funkcje i mogą być konieczne, należy wspomnieć w pliku Readme.
Konsystencja
Upewnij się, że wszystko, nawet komentarze, są spójne w plikach
.hi.cpp.Zachowaj tylko powiązane funkcje w jednym pliku. Posiadanie kilku małych, ale logicznie spójnych modułów jest lepsze niż jeden ogromny plik z zawartością.
Zaawansowane porady
Szczegółowy plik Readme
Napisz przejrzysty plik readme opisujący bibliotekę, jej możliwości, problemy i błędy oraz podstawową użyteczność. Użyj osobnego pliku do zdefiniowania i wyjaśnienia każdego interfejsu, jak opisano powyżej.
Struktura katalogów
Gdy biblioteka stanie się duża, konieczne może być podzielenie jej na katalogi. Nie jest to łatwo możliwe przy użyciu arduino-ide . Ale jeśli doszedłeś tak daleko, prawdopodobnie jesteś zaawansowanym użytkownikiem Arduino i korzystasz z bardziej zaawansowanych narzędzi programistycznych. Jeśli nie, to wszechświat każe ci to zrobić.
Koncesjonowanie
Pamiętaj, aby dodać licencję.
Kontrola wersji
Użyj narzędzia VCS, takiego jak Git lub SVN. Ułatwi to zobaczenie wprowadzonych zmian, powrót do starych wersji, wykrycie błędu powodującego błąd, a nawet współpracę z innymi.
źródło
Odpowiedź AshRj jest bardzo dobra - mam tylko 2 punkty do dodania.
Punkt 1: Dokumentacja
AshRj zalecił napisanie szczegółowego pliku Readme. Chociaż może to być dobra praktyka, może szybko wymknąć się spod kontroli z większymi bibliotekami - w rzeczywistości nawet przy kilku tysiącach wierszy (co jest naprawdę niewiele), readme nie przyniesie prawie żadnych korzyści. Polecam pójść o krok dalej i użyć odpowiednika Javadocs dla C ++ - jak wyjaśnia ta odpowiedź (dotyczy przepełnienia stosu), Doxygen jest bardzo przydatnym narzędziem do zarządzania dokumentacją i zarządzania nią (nikt nie chce edytować Plik readme o rozmiarze 10 KB ...)
Punkt 2: Katalogi
Ponownie, w przeciwieństwie do odpowiedzi AshRj, zawsze używaj katalogów. Nawet jeśli masz tylko 10 plików, może nawet 7 lub 8. Wiem, że to brzmi trochę głupio, ale to zabezpiecza twoją przyszłość na przyszłość, a jeśli nie zaczniesz wcześnie, po prostu skończy się bałagan akta. Katalogi nie są przeznaczone tylko do dużych projektów - również małe powinny z nich korzystać. Pamiętaj tylko, że w C ++ (de facto język Arduino) katalogi są ignorowane przy dołączaniu plików z biblioteki - istnieją tylko jako narzędzie do zarządzania kodami.
źródło