Clean Code — Pragmatic AI Coding Standards

Clean Code — прагматичные стандарты написания кода с использованием ИИ

Критически важно: будь кратким, прямым и ориентированным на результат.

Основные принципы

• SRP (Single Responsibility) — каждая функция или класс делает только ОДНО.
• DRY (Don’t Repeat Yourself) — избегай дублирования, выноси повторяющийся код.
• KISS (Keep It Simple) — выбирай самое простое рабочее решение.
• YAGNI (You Aren’t Gonna Need It) — не добавляй функциональность «на будущее».
• Правило бойскаута — оставляй код чище, чем нашёл.

Правила именования

• Переменные: должны отражать смысл — userCount, а не n
• Функции: глагол + существительное — getUserById()
• Булевы значения: в форме вопроса — isActive, hasPermission
• Константы: SCREAMING_SNAKE_CASE — MAX_RETRY_COUNT

Если имя требует комментария — значит, его нужно переименовать.

Правила для функций

• Маленькие: до 20 строк, лучше 5–10
• Одна задача: функция делает одну вещь и делает её хорошо
• Один уровень абстракции
• Минимум аргументов: максимум 3 (лучше 0–2)
• Без побочных эффектов: не изменяй входные данные неожиданно

Структура кода

• Guard clauses: ранние возвраты для крайних случаев
• Плоская структура: избегай глубокой вложенности (не более 2 уровней)
• Композиция: собирай поведение из маленьких функций
• Локальность: держи связанный код рядом

Стиль работы с ИИ

• Попросили функцию — сразу реализуй
• Сообщили об ошибке — исправь, без лишних объяснений
• Нет чётких требований — уточни, не додумывай

Антипаттерны (чего НЕ делать)

• ❌ Комментировать каждую строку → ✅ удалить очевидные комментарии
• ❌ Создавать helper ради одной строки → ✅ встроить код
• ❌ Фабрика ради двух объектов → ✅ создать напрямую
• ❌ utils-файл с одной функцией → ✅ разместить рядом с использованием
• ❌ «Сначала импортируем…» → ✅ просто писать код
• ❌ Глубокая вложенность → ✅ использовать guard clauses
• ❌ Магические числа → ✅ именованные константы
• ❌ God-функции → ✅ разделить ответственность

Перед изменением любого файла (думай сначала)

Перед внесением изменений задай себе вопросы:

• Кто импортирует этот файл?
• Что импортирует этот файл?
• Какие тесты его покрывают?
• Это общий компонент?

Правило: изменяй файл вместе со всеми зависимыми файлами в рамках одной задачи. Не оставляй сломанные импорты.

Краткое резюме

• Пиши код сразу — не объяснения
• Пусть код говорит сам за себя
• Исправляй баги сразу
• Не усложняй структуру
• Давай понятные имена
• Держи функции маленькими

Пользователю нужен работающий код, а не лекция по программированию.

Самопроверка перед завершением

• Цель выполнена?
• Все нужные файлы изменены?
• Код работает?
• Нет ошибок линтера и типов?
• Учтены крайние случаи?

Если хотя бы один пункт не выполнен — исправь перед завершением.

Работа с проверочными скриптами

После выполнения задачи необходимо:

• Запустить соответствующий скрипт
• Проанализировать вывод (ошибки, предупреждения, успехи)
• Сформировать краткое резюме
• Спросить пользователя, нужно ли исправлять ошибки
• После исправлений — запустить снова

Игнорирование результатов проверки или автоматическое исправление без подтверждения — нарушение процесса.