claude-howto/uk/clean-code-rules.md

<!-- i18n-source: clean-code-rules.md -->
<!-- i18n-source-sha: 63a1416 -->
<!-- i18n-date: 2026-04-10 -->

# Правила чистого коду для 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