Стиль программирования и оформления кода AMS

Здесь представлен стиль программирования и оформления кода проекта Arduino Mega Server. Стиль охватывает такие языки программирования, как C++ (Wiring), Processing, JavaScript, PHP, а также HTML и CSS. Каждый приём программирования или правило оформления кода сопровождаются комментарием, поясняющим причину того или иного решения. В основном всё, что здесь написано, относится к C-подобным языкам программирования, в случае рассмотрения других языков, об этом будет указано отдельно.

Оформление кода

Отступы

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

void func() {
  int a = 0; 
}

Пробел даёт большую гибкость в оформлении кода, чем табуляция и позволяет оперативно варьировать величину отступа. Отступы в два пробела относятся ко всем языкам программирования, используемым в проекте Arduino Mega Server.

Пробелы в коде

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

for (int i = 0; i < 10; i++) { 

Фигурные скобки в циклах и функциях

Открывающая фигурная скобка в циклах и функциях ставится на той же строке, что и сам цикл или функция и отделяется от круглой скобки одним пробелом

void func() {
}

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

void func() {int a = 0;}

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

Циклы for

В циклах после for ставится пробел, а после открывающей круглой скобки и перед закрывающей не ставится.

for (int i = 0; i < 10; i++) {

Конструкция if else

Конструкция if else записывается таким образом, чтобы отражать логическую вложенность.

if ( ) {
  ...
} else {
    ...
  }

Комментарии

Однострочные комментарии

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

// comment

Если комментарий большой, можно использовать несколько однострочных комментариев

// comment 1
// comment 2

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

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

int a = 0; // comment

Комментирование функций

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

} // func()

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

} // func( )

Это всё сделано для удобства чтения кода и упрощения понимания логики его работы.

Многострочные комментарии

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

/*
  ...
  ...
*/

Это сделано для того, чтобы можно была беспрепятственно использовать многострочные комментарии для комментирования участков кода при отладке и написании программы.

Примечание. Если в тексте программы встретится многострочный комментарий, то возникнут проблемы с комментированием этого участка кода при его отладке

Структурные разделители

В тексте программ допускается использовать структурные разделители, которые визуально разграничивают одни участки кода от других. Например

// block ----------------------------------------
/* block
-------------------------------------------------- */
/* block
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */

Наименование констант, переменных и функций

Предопределённые константы

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

#define MY_CONST 10

Название константы пишется большими буквами и отдельные слова в нём разделяются символом подчёркивания.

Имена переменных и функций

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

int myVar;

Аббревиатуры пишутся на общих основаниях, начиная с заглавной буквы и со всеми остальными строчными.

int myHtmlVar;

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

Принципы оформления

Принцип компактности

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

Ширина экрана

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

Табличное форматирование

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

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

void nooOn     (byte ch) {nooSendCommand(ch,  2, 0, 0);}
void nooOff    (byte ch) {nooSendCommand(ch,  0, 0, 0);}
void nooTrigger(byte ch) {nooSendCommand(ch,  4, 0, 0);}

При этом сразу становится видна вся структура алгоритма и сразу становятся видны все мелкие технические ошибки, которые трудно заметить, если тот же код будет растянут на десятки экранов вниз.

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

Программирование

Структурное программирование

Алгоритм желательно составлять таким образом, чтобы не получались многокилометровые листинги, его лучше структурно оформлять в компактные функции с понятными названиями.

Принцип самодокументирования

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

Глобальные переменные

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

Ограничения типов

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

Магические числа

Рекомендуется избегать использования в программе «магических» чисел, назначение и смысл которых может быть непонятен. Всегда лучше ввести предопределённую константу с понятным названием и всегда использовать её в программе.

Оформление кода CSS

Определения классов и идентификаторов в CSS производится подобной конструкцией.

.my-class {
  color: #777;
}

Слова в названии отделяются друг от друга дефисом, отступ стандартный — два пробела, свойства и их значения разделяются одним пробелом.

Комментирование в CSS

Комментирование в CSS производится конструкцией

/* comment */ 

Эта же конструкция используется и для комментирования участков кода при отладке.

Оформление кода HTML

Оформление кода HTML производится стандартным образом, с отображением иерархической структуры и отступом в два пробела.

<div class="level">
<div class="block">

</div>
</div>

Комментирование в HTML

Комментирование в HTML производится конструкцией

<-- comment -->

Эта конструкция используется и для комментариев в HTML коде и для комментирования участков кода при отладке.

Заключение

Это простые правила, которые позволят вам понять как написан код проекта Arduino Mega Server и самим грамотно изменять и дополнять его. Эти же правила вы можете использовать и в других своих проектах.


Обратите внимание. Система Arduino Mega Server непрерывно развивается и в код проекта постоянно вносятся изменения и улучшения, поэтому, описание и документация может не соответствовать вашей конкретной версии системы. Последняя правка этой страницы относится к 0.16 версии системы.