Чистый код для Arduino и Raspberry Pi

Кратко

Код должен быть читаемым прежде всего для человека: придерживайтесь согласованных стилей, понятных имён, небольших функций и ясных комментариев. В статье — практические рекомендации и контрольные списки для Arduino, Raspberry Pi (Python) и общего использования.

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

Что значит «чистый код» — простое определение

Чистый код — это код, который легко понять с первого взгляда: он выражает намерение автора, минимизирует неожиданности и разделён на небольшие, независимые части. Один короткий тезис: читаемость важнее «крутости» приёмов.

Важно: этот материал ориентирован на практику, а не на академические споры о стиле. Если в проекте есть официальный стиль — следуйте ему.

Почему это важно для Arduino и Raspberry Pi

• На Arduino часто мало памяти: лишние повторения и непонятные конструкции увеличивают прошивку.
• На Raspberry Pi вы чаще используете Python — язык, где читаемость и отступы критичны.
• Встроенные проекты обычно поддерживают аппаратные интерфейсы и сторонние библиотеки; понятный код снижает риск аппаратных ошибок.

Основные принципы (кратко)

• Будьте последовательны.
• Пишите понятные имена переменных и функций.
• Комментируйте «почему», а не «что» (когда это не очевидно).
• Держите функции короткими и однозадачными.
• Избегайте излишних компактных приёмов (чтобы не терять читабельность).

Последовательность в стиле кода

Последовательность — самый простой и самый эффективный шаг. Она включает:

• единый стиль именования (snake_case, camelCase и т.д.),
• одно правило для отступов (число пробелов или табы),
• единую стратегию для комментариев и документации.

Пример для Python (Raspberry Pi): следуйте PEP 8: переменные и функции — в lower_case_with_underscores, классы — CapWords.

Пример для Arduino (C/C++): многие руководства применяют camelCase для переменных и функций, либо mixedCase, а макросы — верхним регистром.

Совет: зафиксируйте решения в файле CONTRIBUTING.md или в репозитории проекта — чтобы новые участники знали правила.

Варианты соглашений и когда их выбирать

• PEP 8 (Python): когда проект ориентирован на сообщество Python или использует стандартные библиотеки.
• Arduino style (микроконтроллеры): когда основной код — C/C++ и нужно следовать привычным для сообщества паттернам.
• Проектный стиль: в больших проектах лучше иметь собственный стиль, согласованный в команде.

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

Имена: делайте намерение очевидным

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

Плохой пример:

int x; // количество секунд ожидания

Хороший пример:

int timeoutSeconds; // время ожидания в секундах

Для Python:

def read_moisture_sensor(pin):
    """Считать значение с датчика влажности, подключённого к pin."""
    pass

Подсказки:

• Включайте единицы измерения в имя, если это важно (например, temperature_c или distance_mm).
• Избегайте аббревиатур, если они не общеизвестны.
• Для булевых значений используйте префиксы is, has, should_ (is_connected, has_error).

Комментарии: почему важнее чем «что»

Комментарии полезны, когда они добавляют информацию, которую код не может отразить сам. Плохие комментарии повторяют код; хорошие — объясняют намерение или ограничения.

Плохой комментарий:

// инкремент счётчика
counter++;

Хороший комментарий:

// Инкрементируем счетчик пакетов. Это позволяет отличать потерянные пакеты
// от повторной отправки при восстановлении соединения.
counter++;

Рекомендации:

• Пишите полными предложениями.
• Объясняйте причину: почему выбран этот алгоритм, почему нижняя строчка важна.
• Для Python следуйте PEP 257: docstring для модулей, функций и классов.
• Для Arduino и микроконтроллеров документируйте аппаратные зависимости: какие пины используются, ожидаемые уровни сигнала, тайминги.

Важно: Не комментируйте каждый тривиальный оператор — это создаёт шум.

Упрощайте код: избегайте «умных» сокращений

Короткие и сложные конструкции (например, вложенные тернарные операторы или продвинутые макроприёмы) экономят строки, но усложняют понимание.

Плохой пример (тернарный, тяжело читаемый):

int x = 5;
int y = (x < 10) ? 1 : 0;
printf("%i\n", y);

Гораздо понятнее:

int x = 5;
int y;
if (x < 10) {
    y = 1;
} else {
    y = 0;
}
printf("%i\n", y);

Советы:

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

Отступы и пробелы: форматирование как сигнал намерения

Отступы структурируют код и показывают вложенность. Для Python это не только удобство — это синтаксис.

Рекомендации:

• Выберите фиксированное число пробелов (часто 4) и используйте его везде.
• В большинстве современных редакторов можно настроить замену таба на пробелы.
• Используйте автоматические форматтеры (black для Python, clang-format для C/C++), чтобы снять спор о стиле.

Примечание: Arduino IDE по умолчанию ставит два пробела при нажатии Tab; это допустимо, главное — последовательность.

Не повторяйся — DRY

DRY (Don’t Repeat Yourself) помогает избежать расхождений в логике и облегчает изменения. Повторяющийся код означает, что при исправлении вы можете забыть обновить одну из копий.

Пример: если вы трижды копируете обработку сенсора, вынесите её в функцию read_sensor(), а параметры сделайте аргументами.

Практика:

• Используйте функции и модули для повторяющейся логики.
• Для повторяющихся кусочков конфигурации — централизуйте значения в одном файле с комментариями.
• Встраиваемые проекты: вынесите константы пинов и таймингов в отдельный конфиг-файл.

Явность лучше неявности

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

Плохой пример:

if (buttonPressed) {
    doSomething();
}

Явный эквивалент:

if (buttonPressed == true) {
    doSomething();
}

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

Практическая мини-методология рефакторинга (шаги)

1. Напишите набор базовых тестов или сценариев проверки (валидные и невалидные входы).
2. Соберите текущую базу: статический анализ, list of TODOs, проблемные места.
3. Выберите границу пилота: один модуль или функция менее 200 строк.
4. Примените форматтер и линтер (black, pylint, clang-format, cppcheck).
5. Рефакторите маленькими шагами: один коммит — одна логическая смена.
6. Запустите тесты и проверяйте производительность/память на микроконтроллере.
7. Документируйте изменения в CHANGELOG и обновите CONTRIBUTING.md.

Эта методология уменьшает риск регресса и делает рефакторинг повторяемым.

Контрольные списки по ролям

Разделю список на несколько типичных ролей: разработчик, ревьюер, лидер команды и энтузиаст‑хоббист.

Разработчик — перед пушом:

• Код компилируется/интерпретируется без ошибок.
• Пройдены локальные тесты или сценарии на плате.
• Имена переменных понятны и описательны.
• Нет повторного кода — вынесено в функцию.
• Комментарии объясняют причину, а не повторяют код.
• Добавлен краткий комментарий по аппаратным зависимостям (пины, тайминги).

Ревьюер — на ревью PR:

• Стиль кода соответствует проектному соглашению.
• Функции небольшие и делают одну вещь.
• Нет магических чисел — все константы документированы.
• Производительность/потребление памяти в пределах ожидаемого.
• Тесты покрывают критические ветки.

Лидер команды — при принятии стиля проекта:

• Объяснены причины выбранных решений (README/CONTRIBUTING).
• Настроены CI-инструменты: линтеры, автоформаттеры, тесты на каждом PR.
• Документация по модулям и аппаратному слою обновлена.

Хоббист — быстрый чек перед выкладкой кода:

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

Примеры тест-кейсов и критериев приёмки

Критерии приёмки минимального модуля чтения датчика влажности:

• Модуль возвращает значение в диапазоне ожидания (0–1023 для АЦП) при подключённом датчике.
• Модуль корректно обрабатывает отсутствующий датчик (например, возвращает None или -1 и логирует ошибку).
• Установлен регресс-тест: при эмуляции сигналов тест проходит.

Тесты можно писать как unit-тесты для логики (на хосте), и простые интеграционные тесты на плате.

Когда советы не работают — типичные противопримеры

• Микрооптимизации ради скорости, когда читаемость приносится в жертву, могут быть оправданы если у вас жёсткие ограничения памяти/ЦП. В таком случае — документируйте причину и создавайте «объясняющую» версию кода для разработчиков.
• Экспериментальный код, прототипы и POC (proof-of-concept) могут быть жёстко временными; там можно допустить нарушение некоторых правил, но пометьте это как эксперимент.

Альтернативные подходы

• Строгая автоматизация: используйте автоформаттеры и стопроцентное согласование стиля через CI (этот подход упрощает ревью).
• Мягкая гибкость: разрешайте некоторую вариативность в стиле, но требуйте документацию и тесты.

Какой подход выбрать — зависит от команды: в больших командах автоматизация предпочтительнее.

Краткий словарь терминов

• DRY — не повторяйся.
• PEP 8 — руководство по стилю Python.
• Linters — инструменты статического анализа кода.
• Refactor — изменить структуру кода без изменения поведения.

Шпаргалка и шаблоны (cheat sheet)

Шаблон заголовка файла (README для модуля):

Название модуля: Короткое описание
Назначение: Что делает модуль
Зависимости: библиотеки, аппаратные связи
Использование: пример вызова
Параметры: объяснение аргументов и единиц измерения
Ограничения: известные проблемы

Пример конфигурационного файла (константы.pde / constants.h):

// Пины
const int PIN_PUMP = 7; // цифровой вывод, уровень HIGH включает помпу
const int PIN_SENSOR = A0; // аналоговый вход для датчика влажности

// Тайминги
const unsigned long PUMP_ON_MS = 5000; // миллисекунды

Как проверять читаемость кодовой базы — быстрый чек

1. Можете ли вы объяснить, что делает функция, за 30 секунд? Если нет — она слишком большая или плохо названа.
2. Есть ли повторяющийся код? Если да — стоит вынести в функцию.
3. Все ли аппаратные зависимости задокументированы?
4. Проходят ли тесты и профилирование на целевой плате?

Отказоустойчивость и безопасность

• Проверяйте ввод со стороны датчиков: защищайте от переполнения и некорректных сигналов.
• Для беспроводных интерфейсов документируйте и валидируйте данные по протоколу.
• Встраиваемые проекты: предусмотрите безопасное состояние при ошибках (например, отключение моторов).

Источники для продолжения изучения

• Официальный PEP 8 и PEP 257 — для Python.
• Официальные руководства Arduino и API.
• Книга “Clean Code” — полезна для ментальных моделей и приёмов рефакторинга.

Итог и действия на практике

• Выберите и задокументируйте стиль проекта.
• Настройте линтеры/автоформаттеры в CI.
• Пишите короткие функции и понятные имена.
• Комментируйте, чтобы объяснять причину, а не дублировать код.

Важно: начните с малого — применяйте один принцип и постепенно расширяйте набор практик.

Фото: Dry Bed (Premasagar), Little TAB Key (Kai Hendry), 2015 (Wikilogia)