7.8 KiB
title | description | published | date | tags | editor | dateCreated |
---|---|---|---|---|---|---|
Руководство по стилю программирования Style Guide | Style guidelines used within the Speeduino firmware | true | 2021-01-12T12:46:53.403Z | markdown | 2021-01-02T04:57:03.173Z |
Цель
Программное обеспечение Speeduino стремится к общему, унифицированному подходу к компоновке кода на основе рекомендаций на этой странице. Любые запросы или представления должны в максимально возможной степени соответствовать этим рекомендациям.
Замечания о соблюдении MISRA
Speeduino стремится к соблюдению стандарта кодирования MISRA C:2012, и многие из приведенных ниже конвенций должны соответствовать этому. Полное описание требований MISRA C:2012 выходит за рамки данного документа, но код включает скрипт сканирования MISRA, основанный на cppcheck, который можно использовать для проверки изменений кода
Детали
Структура файла
В программных кодах ('.ino') элементы должны располагаться в следующей последовательности:
- Обязательный комментарий к заголовку, описывающий назначение файла
- включенные файлы (
#include
) - определения (
#define
) - локальные типы структуры local struct typedefs
- локальные пототипыр local prototypes
- Определения любых глобальных переменных global vars
- Основная функция (при наличии) Main function
- Локальные функции Local functions
В заголовке C (.h
) элементы файла должны располагаться в следующей последовательности:
- Комментарий к заголовку Header comment
- защита подключения ifndef guard
- включенные файлы (
#include
) - определения (
#define
) - определения структур struct typedefs
- пототипы prototypes
- (внешние) глобальные переменные (extern) global vars
Имена файлов
Все имена должны быть значимыми и соответствовать существующим шаблонам использования, если они имеются.
Соглашения о присвоении имен
Предмет | Стандарт | Пример |
---|---|---|
Функция | camelCase, с строчная первая буква, нет пробелов или _ | readSensor(); |
Переменные | Также как функции | sensorValue = 0; |
Анонимные переменные (например, некоторые счетчики циклов) | Однострочная буква (предпочтительный порядок или использование: x, y, z, i) | x++; |
Постоянные | ВЕРХНИЙ_РЕГИСТР, слова, соединенные с _ | #define TWO_SQUARED 4 |
Макет и пробел Layout and whitespace
- Использование пробелов для отступов, а не табуляции
- Отступы 2 пробела на уровень
- Всегда использовать {}, даже для отдельных блоков инструкций
- описывать структуры блоков с помощью отступа, не полагаться только на {}
- Для блоков с несколькими линиями скобки всегда должны иметь собственную линию:
void readSensors()
{
analogRead(sensor1);
analogRead(sensor2);
}
- Однострочные блоки (операторы if/else и т.д.) должны находиться в одной строке и содержать фигурные скобки
- При использовании в одной строке должно быть заключительное пространство после {и предшествующее пространство перед}
if(fanEnabled) { digitalWrite(fanPin, HIGH); }
Декларации Declarations
- Объявить переменные в верхней части функции
- В блоке связанных определений вертикальное выравнивание имен, типов и инициализаций
- Инициализируйте переменные, близкие к месту их первого использования.
Функции Functions
- Также поместите возвращаемый тип в ту же строку, что и имя функции
- Функции должны быть короткими и разбиваться на подфункции по мере необходимости
- Каждая функция должна иметь одну четко определенную цель, эта цель должна быть отражена в её названии.
Исполняемые инструкции Executable Statements
- По одному на строку, не i=0; j=0;
- При необходимости допускается выполнение нескольких операций в каждой строке. Например: i = j = 0;
- Правда/Ложь - True/False, если операторы always используют сравнение (либо 0, либо 1, либо true и false). Например:
- Good:
if(isEnabled == 1)
- Bad:
if(isEnabled)
- Good:
- Не используйте оператор запятой для нескольких определений переменных в одной строке
Определения функций Function definitions
- Использовать встроенную статику для всех неинтерфейсных функций
- Использовать прототипы для всех функций (даже возвращаемых int или void)
- Не отключать проверку типа параметра в прототипах с помощью (), используйте вместо этого (void)
- Давайте понятные имена переменных в прототипах
Комментарии Comments
- НАСТОЯТЕЛЬНО рекомендуется использовать синтаксис комментария Doxygen (http://www.doxygen.nl/manual/docblocks.html)
- Комментарии блоков должны использоваться для любого отдельного комментария длиннее одной строки
- Отдельные комментарии предпочтительны в конце строки, а не в их собственной строке заранее