Я працюю над проектом Arduino, використовуючи Uno. Проект містить значну кількість коду. Я хотів би створити бібліотеку і, можливо, згодом навіть поділюсь нею. Яких рекомендацій слід дотримуватися під час проектування бібліотеки?
Відповіді:
Є багато моментів, про які слід пам’ятати, розробляючи бібліотеку. Як ви, напевно, в кінцевому підсумку ділитесь своєю роботою з іншими, надзвичайно важливо дотримуватися послідовних моделей дизайну. Майте на увазі, що інші користувачі матимуть надзвичайно різний рівень кваліфікації, тому створіть просту у користуванні бібліотеку максимально можливою.
Укажіть основну карту контактів, яку очікує ваша бібліотека. Не тримайте статичне відображення статичним, але дозволяйте користувачеві легко вносити зміни.
Одне з перших, що слід спробувати переконатися, - це те, що ваша бібліотека працює. Якщо це не так, чітко констатуйте так. Ви б не хотіли витрачати свій час, намагаючись працювати зі зламаним програмним забезпеченням, тому не дозволяйте і іншим.
Дуже чітко згадуйте, для якої дошки (бібліотек) була розроблена бібліотека, для якої вона була протестована та на якій дошці (іх) вона буде працювати. Вкажіть генерацію (версію) кожної згаданих тут дощок.
Наступне - ви повинні мати чітко визначені інтерфейси. Робоча бібліотека зі стислими інтерфейсами розчаровує. Це допоможе вам згодом самостійно користуватися бібліотекою та полегшить роботу іншим користувачам. Це має бути одним із найважливіших аспектів, які слід пам’ятати.
Незалежно від того, чи дотримуєтесь ви підходу "зверху вниз" або "знизу вгору", інтерфейси завжди повинні бути зрозумілими. У підході знизу вгору це може бути і буде важким, але його не слід ігнорувати. В іншому випадку ви отримаєте надмірно складну бібліотеку, яка може бути непридатною для використання.
Якщо у вас є функції, які використовують якісь особливі характеристики плати, переконайтеся, що ці функції виділяються, згадуйте в readme, а також у коментарях.
Можливо, існують сценарії, коли, можливо, доведеться використовувати зайняте очікування. Такі функції, залежно від логіки програми, можуть перешкоджати нормальному потоку управління, тим самим спричиняючи неприємності, перебуваючи в середині критичного завдання. Спробуйте використовувати переривання або інші алгоритми, якщо це можливо. Якщо ні, то чітко зазначте позначення будь-яких таких функцій.
Не забудьте продовжувати коментувати всі ваші невеликі та великі зміни. Пишіть приємні довгі коментарі до всіх критичних функцій та менші для інших. Явно опишіть свій інтерфейс, кожен аргумент, що він робить і що повертає. Це багато зайвої роботи, але буде дуже корисно як для вас, так і для інших. Якщо у вас є функції, які можуть не працювати на різних дошках, згадайте це тут. Якщо це проміжні функції, які використовуються іншими функціями і можуть знадобитися, згадайте в Readme.
Переконайтесь, що всі, навіть коментарі, узгоджуються між файлами .hта .cppфайлами.
Зберігайте лише пов’язані функції в одному файлі. Маючи кілька невеликих, але логічно послідовних модулів, краще один величезний файл із усім, що в ньому є.
Напишіть чіткий файл readme, який описує бібліотеку, її здібності, будь-які проблеми або помилки та основні зручності використання. Використовуйте окремий файл для визначення та пояснення кожного інтерфейсу, як описано вище.
Щойно бібліотека стає великою, її може знадобитися поділ на каталоги. Це неможливо легко при використанні ардуїно-іде . Але, якщо ви досягли цього далеко, ви, ймовірно, досвідчений користувач Arduino і використовуєте більш потужні інструменти розробки. Якщо ні, то всесвіт говорить вам про це.
Обов’язково додайте ліцензію.
Використовуйте інструмент VCS, такий як Git або SVN. Це значно полегшить перегляд внесених змін, повернеться до старих версій, виявить код помилки на місці та навіть співпрацює з іншими.
Відповідь AshRj дуже хороша - у мене є лише два бали, щоб додати її.
Пункт 1: Документація
AshRj рекомендував написати детальну інформацію. Незважаючи на те, що це може бути хорошою практикою, воно може швидко вийти з рук з більшими бібліотеками - адже навіть у кількох тисячах рядків (що насправді не так багато), readme не матиме майже ніякої користі. Моя рекомендація полягала б у тому, щоб піти на крок далі та використовувати еквівалент Javadocs для C ++ - як пояснюється ця відповідь (це стосується переповнення стека), Doxygen є дуже корисним інструментом для збереження документації, керованої та вручну (ніхто не хоче редагувати Файл readme 10K рядків ...)
Точка 2: Довідники
Знову протиставляючи відповідь AshRj, завжди використовуйте каталоги. Навіть якщо у вас є лише 10 файлів, можливо, навіть усього 7 або 8. Я знаю, що це звучить трохи нерозумно, але це підтверджує вашу роботу в майбутньому, і якщо ви не починаєте рано, ви просто закінчитеся безладом файли. Каталоги не тільки для великих проектів - малі повинні використовувати їх також. Пам'ятайте лише, що в C ++ (де-факто ардуїнська мова) каталоги ігноруються при включенні файлів з бібліотеки - вони існують лише як інструмент управління кодом.