Стильный гайд для Embedded Learning Library (ELL)

Python

Мы используем PEP 8 с одним исключением: мы расширяем ограничение на 80 символов в строке до 120.

C++

Имена файлов и расширения

Файлы заголовков используют расширение ".h". Определения функций, которые должны находиться в заголовке, следует переместить в конец файла заголовка в области, ограниченной блоками #pragma region implementation/#pragma endregion implementation. Файлы исходного кода используют расширение ".cpp", если они компилируются в .lib или .exe. Каждый файл обычно содержит один класс, и его имя должно совпадать с именем класса.

Проекты

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

Именование проектов:

Проекты имеют имена в стиле camelCase, предпочтительно односложно, например, "model", "utilities", "compile".

Именование директорий, пространств имен, выходных данных:

Все исходные файлы в проекте должны быть определены в пространстве имен, совпадающем с именем проекта. Все исходные файлы, связанные с проектом, должны быть расположены в директории, совпадающей с именем проекта. Выходной исполняемый файл или библиотека, сгенерированные проектом, должны совпадать с именем проекта.### Структура директорий проекта: Каждый проект находится в директории. Директория содержит файл CMakeLists.txt. Директория обычно содержит следующие поддиректории:* "include", для файлов .h

• "src" для файлов .cpp (если проект не определяет шаблонную библиотеку без файлов .cpp)
• "test" для исходных файлов, определяющих юнит-тесты, запускаемых через ctest
• "doc" для документации, которая не вписывается в исходные файлы. Например, сложные математические алгоритмы могут требовать подробной документации в файле LaTeX, который будет находиться в директории doc

Кроме того, директория может содержать файл README.md.

Именование

Имена должны быть описательными и самоочевидными, а не краткими. Используйте целые слова вместо сокращений. Например, используйте GetFunctionDefinition вместо GetFuncDef. Исключения из этого правила:

• Используйте "Num" как сокращение для "Number"
• Используйте Size для метода класса, возвращающего размер объекта (вместо GetSize)

Классы, структуры, enum классы: используйте PascalCase, например, class MyClass {}; Используйте camelCase для значений перечислений (enum), например, enum MyEnum { valueOne, valueTwo };

Функции, члены и нечлены: используйте PascalCase, например, int GetValue() const { return _value; }

Когда это возможно, имена функций должны быть глаголами в повелительном наклоне, например, GetValue() и Permute(). В частности, функции-получатели (accessor) должны начинаться с Get, например, GetOutputVector().

Исключения из этого правила:* члены-функции, которые возвращают размер объекта, могут быть просто Size()

• функции преобразования типа могут начинаться с To, например, ToString()
• функции, которые возвращают количество элементов в коллекции, могут начинаться с Num, например, NumVariables()Аргументы методов и функций: camelCase, например, int GetValue(int rowIndex, int columnIndex);

Члены-переменные: используйте _ (нижнее подчеркивание), за которым следует camelCase, например, _myMemberVariable

Шаблонные типы: используйте PascalCase и добавьте суффикс "Type", например, template <typename SparseVectorType>

Шаблонные переменные, которые не являются типами: используйте camelCase, например, template <size_t size>

Структура файлов

Все файлы исходного кода должны начинаться с заголовка, который указывает на имя проекта, имя файла и список авторов (см. пример ниже)

Файлы .h должны содержать #pragma once сразу после заголовка

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

////////////////////////////////////////////////////////////////////////////////////////////////////
//
//  Проект:  Embedded Learning Library (ELL)
//  Файл:    FileName.h (libraryName)
//  Авторы:  Author1, Author2
//
////////////////////////////////////////////////////////////////////////////////////////////////////

#pragma once

#include "OtherClassFromThisProject.h"

#include <proj1/include/ClassFromProjectProj1.h>
#include <proj1/include/AnotherClassFromProj1.h>

#include <proj2/include/ClassFromProj2.h>

#include <vector>
#include <string>

В некоторых случаях требуются обычные #ifndef-защиты включения вместо использования #pragma once. В этом случае добавьте имя защиты в комментарий после #endif:

#ifndef MATRIX_H
#define MATRIX_H    ...

#endif // MATRIX_H

Реализации функций

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

double GetValue() const { return _value; }  // встраиваемая реализация в файле .h

double SetValue(double value);  // функция имеет параметры - реализация должна находиться в файле .cpp или области реализации в файле .h

void Next() { _iterator++; _count++; }  // неправильно: реализации с несколькими инструкциями должны находиться в файле .cpp или области реализации в файле .h

Виртуальные функции

виртуальные функции, объявленные в производных классах, должны использовать ключевые слова override или final, а не virtual. Это потому, что override и final подразумевают виртуальные. Удаление virtual защищает от случайного добавления ещё одного виртуального члена-функции вместо переопределения члена-функции из базового класса, особенно в случае, когда виртуальная функция была удалена из базового класса.### Неиспользуемые переменные Переменные, объявленные или определённые, но никогда не считываемые, будут выдавать предупреждение о неиспользуемой переменной на всех компиляторах. Избегайте неиспользуемых переменных по возможности. Если вы не можете удалить неиспользуемую переменную, то пометьте все такие переменные макросом UNUSED. Если переменная используется только в коде, условно компилируемом для отладочных сборок (например, в выражениях assert), она должна быть помечена макросом DEBUG_USED, а не UNUSED. Оба макроса UNUSED и DEBUG_USED определены в файле Unused.h в библиотеке utilities.### Форматирование Используйте clang-format для обеспечения правильного форматирования. Используйте определения в файле .clang-format, который находится в основном каталоге проекта.

Документация

Все публичные классы, функции и переменные, объявленные в файлах .h, должны предшествовать XML-блоком документации. Единственное исключение составляют функции, определённые с =default или =delete, которые не должны документироваться. Каждая строка документации должна начинаться с трёх слешей (///), а первая строка в блоке документации должна содержать тег-сводка. Следуйте этому примеру:

/// <summary> Математическая операция возведения в степень. </summary>
///
/// <param name="base"> Основание степени. </param>
/// <param name="exponent"> Показатель степени. </param>
///
/// <returns> Результат возведения основания степени в степень показателя. </returns>
double Power(double base, double exponent);

/// <summary> Выполняет сортировку на месте. </summary>
///
/// <typeparam name="RandomAccessContainerType"> Тип контейнера, который должен реализовывать оператор квадратных скобок. </typeparam>
/// <param name="container"> [in,out] Сортируемый контейнер. </param>
template <typename RandomAccessContainerType>
void InplaceSort(RandomAccessContainerType& container);

Обработка ошибокФункция assert обычно приводит к немедленному завершению программы, поэтому её следует использовать только в случаях, когда это никогда не должно произойти, если нет логической ошибки в нашем коде. В этом контексте assert документирует существующие инварианты, предусловия и постусловия в коде.Неправильные входные параметры из нашей публичной API или неправильные данные, прочитанные из файла, не должны приводить к завершению программы с помощью assert, так как это затрудняет отладку и не предоставляет полезной информации вызывающему коду. Вместо этого выбрасывайте соответствующий тип исключения, определённый в ~/libraries/utilities/include/Exception.h. Это включает случай notImplemented, который можно вызвать с помощью throw utilities::LogicException(utilities::LogicExceptionErrors::notImplemented);.