Я работаю над проектом Arduino с использованием Uno. Проект содержит значительное количество кода. Я хотел бы создать библиотеку и даже поделиться ей позже. Каким руководствам я должен следовать при разработке библиотеки?

Есть много моментов, которые вы должны иметь в виду при разработке библиотеки. Как вы, вероятно, в конечном итоге поделитесь своей работой с другими, очень важно следовать последовательным шаблонам проектирования. Имейте в виду, что у других пользователей будут очень разные уровни квалификации, поэтому разработайте простую в использовании библиотеку в максимально возможной степени.

Основные советы

Карта контактов

Предоставьте базовую карту контактов, которую ожидает ваша библиотека. Не сохраняйте постоянное отображение контактов, но позволяйте пользователю легко вносить изменения.

Рабочая библиотека

Одна из первых вещей, которую вы должны попытаться убедиться, что ваша библиотека работает. Если это не так, четко сформулируйте это. Вы бы не хотели тратить свое время на попытки работать со сломанным программным обеспечением, поэтому не позволяйте другим делать то же самое.

Основной файл Readme

Очень четко укажите, для какой платы (ей) была создана библиотека, на которой она была протестирована, и на какой плате (ах) она должна работать. Укажите поколение (версию) каждой платы, упомянутой здесь.

Интерфейсы

Следующее, что вы должны иметь четко определенные интерфейсы. Работающая библиотека с замысловатыми интерфейсами разочаровывает. Это поможет вам в дальнейшем пользоваться библиотекой и облегчит жизнь другим пользователям. Это должно быть одним из самых важных аспектов, о которых следует помнить.

Независимо от того, используете ли вы подход «сверху вниз» или «снизу вверх», интерфейс всегда должен быть ясным. При восходящем подходе это может быть и будет сложно, но это не должно игнорироваться. В противном случае вы получите слишком сложную библиотеку, которую нельзя будет использовать.

Специальные функции

Если у вас есть какие-либо функции, которые используют некоторые особые характеристики платы, убедитесь, что эти функции выделены, упомяните в файле readme, а также в комментариях.

Заняты ожидания

Могут быть сценарии, когда вам может потребоваться занятое ожидание. Такие функции, в зависимости от логики программы, могут препятствовать нормальному потоку управления, вызывая проблемы во время выполнения критической задачи. Попробуйте использовать прерывания или другие алгоритмы, если это возможно. Если нет, то четко отметьте отметку о любых таких функциях.

Комментарии

Не забывайте комментировать каждое маленькое и большое изменение, которое вы делаете. Напишите хорошие длинные комментарии для всех критических функций и поменьше для других. Явно опишите ваш интерфейс, каждый аргумент, что он делает и что возвращает. Это много дополнительной работы, но она будет очень полезна как для вас, так и для других. Если у вас есть какие-либо функции, которые могут не работать на разных платах, упомяните об этом здесь. Если это промежуточные функции, используемые другими функциями и могут быть необходимы, упомяните в файле Readme.

консистенция

Убедитесь , что все, даже комментарии, которые согласуются с .hи .cppфайлов.

Храните только связанные функции в одном файле. Наличие нескольких небольших, но логически согласованных модулей лучше, чем один огромный файл со всем в нем.

Дополнительные советы

Подробный Readme

Напишите понятный файл readme, описывающий библиотеку, ее возможности, любые проблемы или ошибки и основные удобства использования. Используйте отдельный файл для определения и объяснения каждого интерфейса, как описано выше.

Структура каталогов

Как только библиотека станет большой, может понадобиться ее разделение на каталоги. Это не легко возможно при использовании arduino-ide . Но, если вы достигли этого уровня, вы, вероятно, опытный пользователь Arduino и используете более мощные инструменты разработки. Если нет, это вселенная говорит вам сделать это.

Лицензирование

Обязательно добавьте лицензию.

Управление версиями

Используйте инструмент VCS, такой как Git или SVN. Это значительно облегчит просмотр внесенных изменений, возврат к старым версиям, выявление кода, вызывающего ошибки, и даже совместную работу с другими.

Ответ AshRj очень хороший - у меня есть только 2 балла, чтобы добавить к нему.

Пункт 1: Документация

AshRj рекомендовал написать подробный файл readme. Хотя это может быть хорошей практикой, он может быстро выйти из-под контроля с большими библиотеками - даже с несколькими тысячами строк (что на самом деле не так много), readme практически не принесет пользы. Я бы рекомендовал сделать еще один шаг и использовать эквивалент Javadocs для C ++ - как объясняется в этом ответе (он посвящен переполнению стека), Doxygen - очень полезный инструмент для хранения и управления документацией (никто не хочет редактировать 10K строка файла readme ...)

Пункт 2: Каталоги

Снова контрастируя с ответом AshRj, всегда используйте каталоги. Даже если у вас есть только 10 файлов, может быть, даже с 7 или 8. Я знаю, это звучит немного глупо, но это защищает вашу работу от будущего, и если вы не начнете рано, вы просто получите беспорядок файлы. Каталоги предназначены не только для крупных проектов, но и для небольших. Просто помните, что в C ++ (де-факто языке Arduino) каталоги игнорируются при включении файлов из библиотеки - они существуют только как инструмент управления кодом.