# Правила чистого коду для AI-генерації коду Ці правила спрямовують генерацію коду для створення підтримуваного, професійної якості коду. ## Змістовні назви - Використовуйте назви, що розкривають намір та пояснюють чому щось існує - Уникайте дезінформації та безглуздих розрізнень (напр., `data`, `info`, `manager`) - Використовуйте вимовні, такі що легко шукаються назви - Назви класів: іменники (напр., `UserAccount`, `PaymentProcessor`) - Назви методів: дієслова (напр., `calculateTotal`, `sendEmail`) - Уникайте ментального маппінгу та кодувань (Угорська нотація, префікси) ## Функції - Тримайте функції маленькими (< 20 рядків ідеально) - Робіть лише одну річ — Принцип єдиної відповідальності - Один рівень абстракції на функцію - Обмежуйте аргументи: 0-2 ідеально, 3 максимум, уникайте аргументів-прапорців - Без побічних ефектів — функція повинна робити те, що каже її назва - Розділяйте команди (зміна стану) від запитів (повернення інформації) - Надавайте перевагу виключенням над кодами помилок ## Коментарі - Код повинен бути самопояснювальним — уникайте коментарів коли можливо - Корисні коментарі: юридична інформація, попередження, TODO, документація публічного API - Погані коментарі: надлишкові, що вводять в оману, або пояснюють поганий код - Ніколи не коментуйте код — видаляйте його (система контролю версій зберігає історію) - Якщо потрібен коментар, подумайте про рефакторинг коду ## Форматування - Тримайте файли маленькими та зосередженими - Вертикальне форматування: пов'язані концепції поруч, порожні рядки розділяють концепції - Горизонтальне форматування: обмежуйте довжину рядка (80-120 символів) - Використовуйте консистентні відступи та командний стиль - Групуйте пов'язані функції разом ## Об'єкти та структури даних - Об'єкти: ховають дані за абстракціями, відкривають поведінку через методи - Структури даних: відкривають дані, мають мінімальну поведінку - Закон Деметри: спілкуйтесь тільки з безпосередніми друзями, уникайте `a.getB().getC().doSomething()` - Не відкривайте внутрішню структуру через геттери/сеттери наосліп ## Обробка помилок - Використовуйте виключення, а не коди повернення або прапорці помилок - Пишіть `try-catch-finally` першим, коли код може не виконатись - Надавайте контекст у повідомленнях виключень - Не повертайте `null` — повертайте порожні колекції або використовуйте Optional/Maybe - Не передавайте `null` як аргументи ## Класи - Маленькі класи: вимірюються відповідальностями, а не рядками - Принцип єдиної відповідальності: одна причина для зміни - Висока зв'язність (cohesion): змінні класу використовуються багатьма методами - Низька зв'язаність (coupling): мінімальні залежності між класами - Принцип відкритості/закритості: відкритий для розширення, закритий для модифікації ## Юніт-тести - Швидкі, Незалежні, Повторювані, Самоперевіряючі, Своєчасні (F.I.R.S.T.) - Один assert на тест (або одна концепція) - Якість тестового коду дорівнює якості продакшен-коду - Читабельні назви тестів, що описують що тестується - Патерн Arrange-Act-Assert ## Принципи якості коду - **DRY (Don't Repeat Yourself)**: Без дублювання - **YAGNI (You Aren't Gonna Need It)**: Не будуйте для гіпотетичного майбутнього - **KISS (Keep It Simple)**: Уникайте зайвої складності - **Правило скаута**: Залишайте код чистішим, ніж ви його знайшли ## Code Smells, яких варто уникати - Довгі функції або класи - Дублювання коду - Мертвий код (невикористані змінні, функції, параметри) - Feature envy (метод більше цікавиться іншим класом) - Inappropriate intimacy (класи знають занадто багато один про одного) - Довгі списки параметрів - Primitive obsession (надмірне використання примітивів замість маленьких об'єктів) - Switch/case (розгляньте поліморфізм) - Тимчасові поля (змінні класу використовуються лише іноді) ## Конкурентність - Тримайте конкурентний код окремо від іншого коду - Обмежуйте область синхронізованих/заблокованих даних - Використовуйте потокобезпечні колекції - Тримайте синхронізовані секції маленькими - Знайте свої моделі виконання та примітиви ## Проєктування систем - Відокремлюйте конструювання від використання (впровадження залежностей) - Використовуйте фабрики, будівельники для складного створення об'єктів - Програмуйте на інтерфейси, а не на реалізації - Надавайте перевагу композиції над успадкуванням - Застосовуйте патерни проєктування коли вони спрощують, а не для демонстрації ## Рефакторинг - Рефакторіть безперервно, а не великими порціями - Завжди майте тести, що проходять, до та після - Маленькі кроки: одна зміна за раз - Поширені рефакторинги: Витягнути метод, Перейменувати, Перемістити, Вбудувати ## Документація - Самодокументований код > коментарі > зовнішня документація - Публічні API потребують чіткої документації - Включайте приклади в документацію - Тримайте документацію близько до коду (ідеально — в коді) --- **Основна філософія**: Код читається в 10 разів частіше, ніж пишеться. Оптимізуйте для читабельності та підтримуваності, а не для хитрості. --- **Останнє оновлення**: Квітень 2026