Arduino:Хакинг/Написание примера

Содержание

Знакомство с Arduino

Продукты

Основы

Справочник языка Arduino

Примеры

Библиотеки

Хакинг

Изменения

Сравнение языков Arduino и Processing

Перевод: Максим Кузьмин

Проверка/Оформление/Редактирование: Мякишев Е.А.

Написание примера

Это руководство по написанию скетчей-примеров для Arduino, которые будут понятны и новичкам, и продвинутым пользователям. Вам необязательно кодить именно так – это руководство лишь призвано показать, как сделать свой код понятным для пользователя любого уровня. Это не набор жестких правил или быстрых приемов. Это набор общих принципов. Более того, некоторые из этих принципов могут друг с другом конфликтовать. Какой из них использовать в своем коде – решайте сами, а если не уверены – посоветуйтесь о том, что лучше оставить/убрать, у человека, который учится по вашему коду. Также рекомендуем обратить внимание на руководство по написанию API для Arduino.

Написание руководства

Здесь скомпилирована выборка из советов от разных авторов:

• Пишите в действительном залоге.
• Пишите понятно и непринужденно, как если бы человек, к которому вы обращаетесь, находился с вами в одной комнате.
• Давая инструкции, пишите от второго лица, чтобы читатель понимал, что именно ему нужно сделать это.
• Старайтесь писать короткие, лаконичные, а не сложные, нагроможденные предложения. Пользователю будет проще переваривать одну инструкцию за раз.
• Давайте указания, лишенные двусмысленности: «Далее считывайте значения с датчика...» или «Создайте переменную под названием thisPin...».
• Избегайте фраз, не добавляющих никакой информации. Не нужно писать «Далее приступите к настройке контактов», пишите «Настройте контакты».
• Используйте не только схемы, но и рисунки/фотографии. Многие электронщики-любители не имеют читать схемы.
• Проверьте свои предположения. Понимает ли читатель идеи, которые вы изложили в своем руководстве? Если нет, объясните или дайте ссылку на другое руководство.
• Изложите общую идею, чтобы читатель понимал более широкую картину того, что он будет делать. После этого приступайте к конкретным, пошаговым инструкциям.
• В первый раз вводя новый технический термин, дайте ему определение. Дайте кому-нибудь проверить свою работу, чтобы он проверил, все ли термины раскрыты. Наверняка найдется один-два, которые вы пропустили.
• Придерживайтесь одних и тех же терминов. Если вы называете компонент или понятие новым словом, свяжите его с первым синонимом. Не используйте синонимы без увязки друг с другом, пока не рассказали пользователю о связи между ними.
• Первый раз используя акронимы и аббревиатуры, раскройте их.
• Не распыляйтесь. Объясните в своем руководстве что-то одно, но объясните хорошо. Не нужно объединять в одном руководстве идеи/функции за исключением случаев, когда руководство как раз рассказывает о том, как объединять их друг с другом.

Написание скетча-примера

• Первостепенна не эффективность, а читаемость.
• Самые важные пользователи Arduino – это новички и люди, которым не важен код, а важно сделать проект.
• Будьте внимательны к людям, которые знают о коде меньше, чем вы. Велика вероятность, что они не поймут некоторые технические концепты, о которых вы им рассказываете. И дело не в том, что они глупы. Ваш код должен объяснять себя сам или при помощи ваших комментариев. Если в скетче используются сложные концепты вроде регистров, прерываний или указателей, то либо объясните их, либо пропустите.
• Если стоит выбор между простотой и эффективностью, выбирайте первое.
• Вводите новые концепты, только если они полезны. Пытайтесь минимизировать количество новых концептов, вводимых в одном скетче-примере. К примеру, в самом начале можно объяснить простые функции, где единственным типом данных будет int, а конструкцией для определения номера контакта – только const. С другой стороны, если вашему скетчу будет полезен какой-нибудь дополнительный концепт, можете смело его использовать. К примеру, можно воспользоваться const int, чтобы задать номер контакта, или типом данных byte вместо int, если вам достаточно чисел в диапазоне 0-255. Правда, начинать с них не рекомендуется. Используйте эти дополнительные концепты экономно и, применяя их впервые, объясняйте, что они значат.
• Поместите блоки setup() и loop() в самом начале скетча. Это поможет новичку увидеть, как устроен скетч, потому что все функции вызываются именно из этих блоков.

Комментирование кода

• Комментируйте объявление каждой переменной/константы с описанием того, что она делает.
• Комментируйте каждый блок кода. Делайте это перед блоком, чтобы пользователь понимал, что происходит.
• Комментируйте каждую строчку в цикле.
• Используя оператор if(), будьте многословны. Чтобы упростить читаемость скетча для новичка, используйте блоковый формат. То есть избегайте этого:

if (somethingIsTrue) doSomething;

• Вместо этого используйте:

if (somethingIsTrue == TRUE) {
   doSomething;
}

• Избегайте указателей.
• Избегайте конструкций #define.

Переменные

• Избегайте называть переменные одним словом. Сделайте их более описательными.
• Избегайте называть переменные вроде val или pin. Вместо этого используйте, к примеру, buttonState или switchPin.
• Если вы хотите задать название контакта или другой неизменный параметр, используйте const int. Они менее замороченные, чем #define, но в то же время позволяют понять, чем переменная отличается от константы.
• Используйте типы переменных в стиле Wiring/Processing: boolean, char, byte, int, unsigned int, long, unsigned long, float, double, string, array, void вместо uint8_t (если возможно) и т.д. Все они объясняются в справочнике языка Arduino и более описательны.
• Избегайте схем нумерации, которые могут запутать пользователя. Например:

pin1 = 2
pin2 = 3
и т.д.

Если вам нужно перенумеровать контакты, используйте массив. Примерно так:

int myPins[] = { 2, 7, 6, 5, 4, 3 };

Это позволит вам ссылаться на новые номера контактов при помощи элементов массива. Например, так:

digitalWrite(myPins[1], HIGH);  // включаем контакт 7

Это также позволяет вам включить/выключить все контакты, используя лишь одно предложение. Примерно так:

for (int thisPin = 0; thisPin < 6; thisPin++) {
   digitalWrite(myPins[thisPin], HIGH);
   delay(500);
   digitalWrite(myPins[thisPin], LOW);
   delay(500);
}

Объясните, что делает скетч

Вот пример того, как должен выглядеть стартовый блок скетча:

/*
	Заголовок скетча

	Доступным языком опишите, что делает этот скетч. Укажите
	компоненты/устройства, подключенные к разным контактам.

	Цепь:
	* список компонентов, подключенных к каждому входному контакту
	* список компонентов, подключенных к каждому выходному контакту

	Создан день/месяц/год автором таким-то.
	Модифицирован день/месяц/год автором таким-то.

	http://url/of/online/tutorial.cc

*/

Цепи

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

Старайтесь делать цепь как можно проще. К примеру, блокировочные конденсаторы весьма полезны, но большинство простых входных линий могут спокойно обойтись и без них. Если используется какой-то второстепенный компонент, его можно объяснить позже.