dev-standards

name	dev-standards
description	Стандарты разработки и имплементации кода. Использовать при написании кода, code review, рефакторинге, TDD разработке на любом языке (TypeScript, Python, C#, и др.). Включает метрики качества, стоп-сигналы сложности, TDD workflow, правила тестирования.

Стандарт разработки

Базовые принципы (ВЫСШИЙ ПРИОРИТЕТ)

1. Писать элегантный код, решающий задачу
2. Не добавлять обратную совместимость без явного запроса
3. После каждого блока кода: линтинг → компиляция → тесты → запуск
4. Предпочитать правку существующего вместо добавления нового
5. Качество превыше скорости — лучше потратить время на качественный код
6. При неуверенности — спросить с озвучиванием рекомендаций

Метрики качества (ОБЯЗАТЕЛЬНО)

Метрика	Лимит
Cyclomatic Complexity	< 10
Длина функции	< 30 строк
Длина класса	< 200 строк
Параметры функции	< 5 (объект для >5)
Вложенность	< 4 уровней

Правило 3-х альтернатив

1. Придумать 3 решения
2. Выбрать простейшее работающее
3. Избегать первого пришедшего в голову

Code Review вопросы (ВСЕГДА задавать себе)

• "Можно ли это сделать проще?"
• "Зачем эта сложность?" (для функций >30 строк)
• "Есть ли стандартное решение?"
• "Понятно ли junior разработчику?"

Стоп-сигналы сложности 🚨

Остановиться и пересмотреть решение при:

• "Это очень умное решение" 🚩
• "Только я понимаю как это работает" 🚩
• "Потом разберёмся" 🚩
• "Тут нужно быть осторожным" 🚩
• Требуется объяснение одного и того же 2+ раза 🚩

Анти-паттерны (ИЗБЕГАТЬ)

• Преждевременная абстракция — абстрагировать только при реальном дублировании
• Generic hell — избегать T<K<V<U>>>
• God-функции — функция делает >3 разных вещей
• Callback ад — >3 уровней вложенности callbacks
• Магические значения — числа/строки без объяснения

Триггеры рефакторинга

Ситуация	Действие
Дебаг >30 мин	Упростить код
Тест сложнее кода	Упростить код
Страшно менять	Упростить архитектуру
Повторяешь объяснение	Добавить комментарий или упростить

Процесс работы с пользователем

1. Обсуждение → исследовать варианты → уточняющие вопросы
2. ТЗ → сформулировать → разбить на задачи → получить подтверждение
3. Реализация → спросить "Приступаем к реализации?" → дождаться подтверждения

TDD (КРИТИЧНО)

Главное правило: Код подстраивается под тест. НИКОГДА не менять тест для исправления ошибок компиляции.

❌ ЗАПРЕЩЕНО: Изменить expect() чтобы тест прошёл
✅ ПРАВИЛЬНО: Изменить имплементацию чтобы соответствовать expect()

Цикл (обязателен для каждой фичи):

1. RED — написать тест ПЕРВЫМ → он должен упасть
2. GREEN — минимальный код → тест проходит
3. REFACTOR — улучшить → тесты остаются зелёными

→ Детали и примеры: references/tdd-workflow.md

Тестирование

Покрытие:

• 100% — критическая логика (платежи, безопасность, заказы)
• 80% — основная бизнес-логика
• 60% — вспомогательный код

Именование тестов:

✅ "should return user when found"
✅ "should throw ValidationError for invalid email"
❌ "test getUser"
❌ "works correctly"

→ Паттерны тестирования: references/testing-patterns.md

Верификация перед завершением

# Обязательная последовательность:
lint        # 0 ошибок
typecheck   # 0 ошибок (для типизированных языков)
test        # Все тесты зелёные
coverage    # Соответствует требованиям

Задача НЕ завершена если:

• ❌ Тесты не проходят
• ❌ Есть ошибки линтера/компиляции
• ❌ Покрытие ниже требуемого
• ❌ TDD цикл не соблюдён