Arduino

и не только...

YouTube Instagram TikTok Telegram VK

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

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

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

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

С появлением сторонних редакторов кода и IDE, таких, как PlatformIO, следить за соблюдением стилистики кода стало намного проще.

Отступы

Первое и самое важное правило: отступы нужно использовать. Обязательно. Давайте сравним такой код:

...
int checkSum()
{
int a;
for (int i = 0; i < 10; i++)
{
a++;
}
return a;
}

и такой:

...
int checkSum()
{
  int a;
  for (int i = 0; i < 10; i++)
  {
    a++;
  }
  return a;
}

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

Размер отступа, а также то, какой символ использовать (пробел или табуляция) выбирается исходя из личных предпочтений. Однако есть устоявшаяся рекомендация: использовать всегда пробелы и не использовать символ табуляции. Это связано с тем, что отображение символа табуляции может быть разным в разных редакторах кода, что делает неудобным чтение кода при открытии его в другом редакторе, не где он был написан. Многие редакторы по-умолчанию конвертируют символ табуляции в символы пробелов.

Чаще всего в коде для Arduino для отступов используется 2 пробела. Реже - 4 или 3.

Пробелы

Пробелы делают код более читаемым. Например сравните:

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

Второй вариант явно удобнее читать. Есть еще такой вариант:

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

Каждый решает сам. Но именно второй вариант наиболее распространен и чаще принято использовать именно его.

Фигурные скобки

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

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

if (a == 1) 
{
  b++;
}

if (a == 1) {
  b++;
}

if (a == 1)
  b++;

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

Ставить открывающуюся скобку на той же строчке или на следующей - вопрос личного выбора. Наиболее частое правило: при написании функции скобка ставится на следующей строчке, а при написании операторов - на той же, отделенная одним пробелом:

void setup()
{
}

void loop()
{
  if (a != b) {
    for (int i = 0; i < 10; i++) {
      a += b;
    }
  }
}

Комментарии

Комментарий - текст, который игнорируется компилятором и служит для лучшего понимание программы при чтении кода.

Для создание однострочного комментария используется два символа прямого слэша - //:

// функция проверки четности числа
bool isEven(int num)
{
  ...
}

Для создание комментария из нескольких строк следует перед началом текста комментария поставить /*, а после текста - */:

/* Функция проверки четности числа.
Входные параметры:
num - целое число 
*/
bool isEven(int num)
{
  ...
}

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