Руководство по стилю написания контента для Arduino

Узнайте, как писать понятные примеры для Arduino, доступные как начинающим, так и опытным пользователям.

Последняя редакция: 17.01.2023

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

Если вы хотите внести вклад в написание контента для сайта документации Arduino, найдите инструкции в папке contribution-templates в репозитории документации Arduino.

Написание туториала

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

  • Пишите активным залогом.

  • Пишите чётко и разговорно, как будто человек, следующий вашим инструкциям, находится с вами в одной комнате.

  • Когда даёте инструкции, пишите от второго лица, чтобы читатель понимал, что именно он будет это делать.

  • Используйте короткие, простые, чёткие предложения и команды вместо сложносочинённых. Читателю легче воспринимать по одной инструкции за раз.

  • Давайте указания однозначно, например:

    • «Далее вы считаете показания датчика…»

    • «Создайте переменную с именем thisPin…»

  • Избегайте фраз, которые не несут информации. Не говорите читателю «Вы хотите настроить пины» — просто скажите ему «Настройте пины».

  • Используйте фотографии и схемы, а не только одни схемы. Многие любители электроники не умеют читать принципиальные схемы.

  • Проверяйте свои предположения. Понимает ли читатель все концепции, которые вы используете в своём туториале? Если нет — объясните их или дайте ссылку на другой туториал, где это объясняется.

  • Объясняйте вещи концептуально, чтобы читатель имел общее представление о том, что он будет делать. Затем излагайте инструкции по использованию шаг за шагом.

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

  • Последовательно используйте термины. Если вы называете компонент или концепцию новым именем — явно укажите его связь с предыдущим названием. Не используйте два термина как взаимозаменяемые, не предупредив об этом читателя.

  • Не используйте аббревиатуры или сокращения без их предварительной расшифровки.

  • Сосредоточьте ваш пример на одном деле. Не совмещайте концепции или функции, если только ваш туториал не посвящён именно совмещению концепций.

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

Эффективность — не главное; главное — читаемость.

Самые важные пользователи Arduino — это начинающие и люди, которым не важен сам код, а важно выполнить проект.

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

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

Вводите концепции только тогда, когда они полезны, и старайтесь минимизировать количество новых концепций в каждом примере. Например, в самом начале вы можете объяснять простые функции, не используя типы переменных кроме int и не применяя константы для определения номеров пинов. С другой стороны, в промежуточном примере вы можете вводить сопутствующие концепции по мере их необходимости. Такие концепции, как использование const int для определения номеров пинов, выбор byte вместо int когда вам не нужны значения выше 0–255 и т.д., полезны, но не являются центральными для начала работы. Поэтому используйте их экономно и объясняйте, когда они впервые появляются в вашем плане урока.

Размещайте

setup()

и

loop()

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

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

  • Комментируйте каждое объявление переменной или константы с описанием того, что делает эта переменная.

  • Комментируйте каждый блок кода. По возможности делайте это перед блоком, чтобы читатель знал, что его ждёт.

  • Комментируйте каждый цикл for.

Используйте развёрнутые операторы if. Для простоты начинающего читателя всегда используйте блочный формат, то есть избегайте такого кода:

if (distance > 10) moveCloser();

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

if (distance > 10) {
   moveCloser();
}

Избегайте указателей.

Избегайте

#defines

Переменные

  • Избегайте однобуквенных имён переменных. Делайте их описательными.

  • Избегайте имён переменных вроде

    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 и т.д. Первые задокументированы в документации и имеют менее краткие названия.

  • Избегайте схем нумерации, которые вводят пользователя в заблуждение, например:

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/онлайн/туториала.cc

*/

Схемы

Для цифровых входных переключателей по умолчанию используйте подтягивающий резистор к минусу (pull-down), а не к плюсу (pull-up). Так логика взаимодействия с переключателем будет понятна не-инженеру.

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