Перейти до основного вмісту

Стандарт кодування

Цей посібник визначає правила надання коду для бібліотеки SiMa.ai Neat.

Обмеження щодо мови та API.​

  • Використовуйте C++20.
  • Зміни у публічному API мають бути обґрунтованими та мінімальними (версію include/* слід вважати стабільною).
  • Віддавайте перевагу розширенням, сумісним зі старими версіями, замість змін, які порушують сумісність.
  • Не розміщуйте внутрішні деталі реалізації в встановлених/публічних заголовкових файлах.

Форматування та дотримання єдиного стилю​

  • Форматування коду C/C++ забезпечується за допомогою clang-format (.clang-format у кореневій директорії репозиторію).
  • Дотримання стилю CMake забезпечується за допомогою scripts/check_cmake_style.py.
  • Повторне включення вхідних файлів у вихідному коді C/C++ заборонено.
  • .editorconfig визначає базові правила щодо пробілів (перехід на новий рядок, остаточний перехід на новий рядок, відсутність зайвих пробілів у кінці рядка).

Запустіть перед відправленням:

bash scripts/check_format.sh --changed-only
bash scripts/check_cmake_format.sh --changed-only
bash scripts/check_duplicate_includes.sh --changed-only

Політика сумісності API​

Сумісність із загальнодоступним API є обов’язковою вимогою для всіх встановлених файлів заголовків, що містяться в include/*.

  • Перевага надається незмінним доповненням (нові перевантаження, нові необов’язкові поля, нові API).
  • Зміни, що порушують сумісність (перейменування/видалення/зміна типу/зміна порядку параметрів/порушення поведінкового контракту), повинні проходити процес перевірки перед об’єднанням.
  • Якщо неминуче потрібно внести зміни, несумісні з попередніми версіями, спочатку передбачте період поступового вилучення (залиште стару сигнатуру + додайте альтернативний спосіб використання), а вже потім видаліть старий код.

Необхідний процес для зламу цифрових підписів API.​

Перед об’єднанням змін, що порушують сумісність API:

  1. Опишіть зміни в описі до запиту на внесення змін (PR) у спеціальному розділі під назвою Breaking API Change.
  2. Включіть аналіз наслідків: перелік задіяних заголовків/символів, очікувані проблеми, які можуть виникнути в подальшому, та етапи міграції.
  3. Вкажіть інформацію про версію/план випуску (коли дозволено випускати оновлення).
  4. Оновіть документацію та приклади, щоб вони відповідали новому API, в рамках одного й того ж набору змін.
  5. Отримайте чітке схвалення від відповідальних за підтримку щодо змін, які впливають на інтерфейс програмування застосунків (API).

Межі модуля​

Дотримуйтеся суворих правил щодо залежностей:

  • builder/ не повинен залежати від GStreamer або pipeline/.
  • gst/ не повинен залежати від pipeline/.
  • nodes/ не повинні залежати від pipeline/.
  • pipeline/ є головним компонентом, який координує роботу та може залежати від gst/, builder/, nodes/, contracts/, policy/ та внутрішніх компонентів моделі.

Вимоги до детермінованості​

  • Вихідні дані вузла повинні бути детермінованими для однакових вхідних даних/налаштувань.
  • Забезпечте стабільність і відтворюваність назв елементів.
  • За можливості, забезпечте детерміноване генерування рядків у конвеєрі.
  • Під час зміни правил іменування переконайтеся, що діагностичні інструменти та процедури перевірки все ще правильно пов’язують елементи з відповідними вузлами.

Обробка помилок і діагностика​

  • Віддавайте перевагу структурованим помилкам із чітким описом та можливістю їх усунення.
  • Переконайтеся, що нові сценарії виникнення помилок містять достатньо інформації для діагностики, яка буде включена до звіту PipelineReport про роботу конвеєра.
  • Уникайте непомітних механізмів резервного копіювання, які приховують помилки плагінів/модулів/середовища виконання.
  • Забезпечте потокобезпечність діагностичних функцій; для оновлення даних на стороні зонда необхідно використовувати атомарні операції або еквівалентні примітиви без блокувань.

Паралельність і життєвий цикл​

  • Ніколи не блокуйте процес на невизначений термін під час виконання процедур завершення роботи.
  • Забезпечте захищений перехід між станами під час роботи програми (EOS, NULL), передбачте безпечні шляхи завершення роботи, що захищають від перевищення часу очікування.
  • Забезпечте, щоб логіка потоку даних для потокового передавання була простою та мала передбачувані побічні ефекти.

Обов’язки щодо ведення документації.​

Коли змінюється поведінка:

  • Оновіть Архітектура.
  • Оновіть довідкові матеріали для користувачів, якщо змінилися робочі процеси або налаштування.
  • Задокументуйте нові змінні середовища в довідковій документації.

Якість у процесі розробки (PR) має бути на високому рівні.​

Матеріал готовий до публікації, якщо він містить:

  • Чітке обґрунтування в коді та повідомленні про внесення змін/запит на об’єднання змін.
  • Тестування нової функціональності та виявлення регресій.
  • Оновлено документацію для будь-яких змін, які будуть помітні користувачам.
  • Оцінка сумісності API для змін у загальнодоступних заголовках (і повний процес внесення несумісних змін, якщо це необхідно).