Корпоративный стандарт код-стайла и инженерных соглашений¶

Цель документа¶

Этот стандарт фиксирует обязательные требования к коду и инженерному процессу проекта Konstructorium. Документ формализует практики, которые уменьшают дефектность, сокращают стоимость сопровождения и делают ревью предсказуемым.

Каждое правило описывается в формате: - Требование - Причина - Как проверить - Корректно / некорректно

Нормативная и доказательная база¶

Основные внешние ориентиры: - PEP 8 — читаемость и единообразие Python-кода. - PEP 257 — договоренности по docstring. - The Twelve-Factor App — операционная зрелость сервисов. - Semantic Versioning — предсказуемость изменений контрактов. - Keep a Changelog — прозрачность изменений.

Внутренняя база проекта: - Стандарты документации - QA стратегия - Управление изменениями

1. Принципы обязательности¶

1.1 Единое применение¶

Требование: стандарт обязателен для всех сервисов, frontend, tests, scripts.
Причина: разные локальные стили повышают когнитивную нагрузку и увеличивают время ревью.
Как проверить: в PR нет аргументации «мы в этом сервисе делаем иначе» без утвержденного исключения.
Корректно: единые паттерны именования и docstring во всех сервисах.
Некорректно: один сервис использует произвольный стиль «по привычке команды».

1.2 Контролируемые исключения¶

Требование: любое исключение из правил документируется в PR и связано с техническим ограничением.
Причина: без формализации исключения быстро становятся новым хаотичным стандартом.
Как проверить: для каждого исключения есть описание риска, срока и условий пересмотра.
Корректно: «временное исключение до миграции X, срок Y, ответственный Z».
Некорректно: «сделал так быстрее, потом поправим».

2. Именование¶

2.1 Общие требования¶

Требование: имена отражают бизнес-смысл, а не техническую случайность.
Причина: семантические имена снижают вероятность ошибок интеграции и неправильного использования API.
Как проверить: по названию символа понятна доменная роль без чтения тела функции.
Корректно: calculate_order_total, is_seller_approved.
Некорректно: do_work, tmp_data, calc.

2.2 Python¶

Требование: snake_case для функций/переменных, PascalCase для классов, UPPER_SNAKE_CASE для констант.
Причина: соответствие отраслевым соглашениям и снижение порога входа для новых разработчиков.
Как проверить: регулярная проверка имен и code review.
Корректно: order_status, OrderSerializer, MAX_RETRY_COUNT.
Некорректно: Order_status, orderSerializer, maxRetryCount.

2.3 JavaScript и React¶

Требование: camelCase для функций и переменных, PascalCase для компонентов, UPPER_SNAKE_CASE для констант.
Причина: единый стиль ускоряет чтение frontend-кода и уменьшает дефекты переиспользования.
Как проверить: проверка экспортируемых сущностей и имен компонентов.
Корректно: loadUserProfile, ProductCard, DEFAULT_PAGE_SIZE.
Некорректно: load_user_profile, product_card.

3. Структура модулей и функций¶

3.1 Единственная ответственность¶

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

3.2 Ограничение сложности¶

Требование: избегать глубоких вложенностей и длинных блоков условной логики.
Причина: высокая цикломатическая сложность повышает риск регрессий.
Как проверить: сложные ветвления декомпозированы в именованные шаги.
Корректно: guard clauses + небольшие подфункции.
Некорректно: вложенные if/else на 4-5 уровней.

4. Docstring и комментарии (максимальный режим)¶

4.1 Python docstring¶

Требование: docstring обязателен для каждого модуля, класса, функции и метода.
Причина: явные контракты делают поведение кода проверяемым и воспроизводимым.
Как проверить: отсутствие сущностей без docstring в исходниках.
Корректно: docstring содержит Args, Returns, Raises, побочные эффекты.
Некорректно: пустой или формальный docstring вида «Do something».

4.2 JavaScript JSDoc¶

Требование: JSDoc обязателен для экспортируемых функций, React-компонентов и сложных внутренних функций.
Причина: типовые ошибки интеграции часто вызваны неявными ожиданиями параметров.
Как проверить: экспортируемая сущность имеет JSDoc с параметрами и результатом.
Корректно: @param, @returns, описание ограничений.
Некорректно: экспорт без описания контракта.

4.3 Комментарии¶

Требование: комментарии объясняют «почему», инварианты, компромиссы и риски.
Причина: комментарии «что делает код» устаревают и не дают инженерной ценности.
Как проверить: перед нетривиальными участками есть контекст решения.
Корректно: пояснение бизнес-правила или технического ограничения.
Некорректно: «увеличиваем i на 1».

5. Обработка ошибок и контракты¶

5.1 Явная обработка ошибок¶

Требование: запрещено подавлять исключения без логирования и объяснения.
Причина: «тихие» ошибки маскируют дефекты и усложняют инцидент-менеджмент.
Как проверить: нет except Exception: pass и аналогов.
Корректно: логирование, контекст, повторный выброс или безопасный fallback.
Некорректно: игнорирование исключения без следа.

5.2 Стабильность публичных контрактов¶

Требование: изменение API/контрактов сопровождается обновлением документации и тестов.
Причина: несинхронные изменения ломают потребителей сервисов.
Как проверить: PR содержит код + docs + тестовую корректировку при изменении контракта.
Корректно: endpoint обновлен и отражен в сервисной документации.
Некорректно: код изменен, docs остались в старом состоянии.

6. Импорты, зависимости, мертвый код¶

6.1 Чистота импортов¶

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

6.2 Запрет мертвого кода¶

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

7. Требования к ревью и готовности PR¶

Код следует стандарту именования и структуры.
Докстринги/JSDoc покрывают все затронутые сущности в максимальном режиме.
Для нетривиальной логики добавлены поясняющие комментарии с причинно-следственной связью.
Изменения в контрактах синхронизированы с документацией и тестами.
Локальная проверка (линтер/тесты) выполнена или ограничение задокументировано.

8. Чек-лист самоаудита разработчика¶

Перед передачей на ревью разработчик обязан подтвердить: 1. Явные и семантические имена в измененных файлах. 2. Наличие docstring/JSDoc для всех затронутых сущностей. 3. Комментарии объясняют мотивы и ограничения, а не очевидные действия. 4. Ошибки не подавляются молча, присутствует диагностический контекст. 5. Документация и код согласованы по API и поведению.