refactor

name	refactor
description	Систематичний рефакторинг коду на основі методології Мартіна Фаулера. Використовуйте, коли користувачі просять рефакторити код, покращити структуру коду, зменшити технічний борг, очистити застарілий код, усунути запахи коду (code smells) або покращити супровідність коду. Ця навичка проводить через поетапний підхід з дослідженням, плануванням та безпечною інкрементальною реалізацією.

Навичка рефакторингу коду

Систематичний підхід до рефакторингу коду на основі книги Мартіна Фаулера Refactoring: Improving the Design of Existing Code (2-ге видання). Ця навичка наголошує на безпечних, інкрементальних змінах, підкріплених тестами.

«Рефакторинг — це процес зміни програмної системи таким чином, що не змінює зовнішню поведінку коду, але покращує його внутрішню структуру.» — Мартін Фаулер

Основні принципи

1. Збереження поведінки: Зовнішня поведінка повинна залишатися незмінною
2. Малі кроки: Робити крихітні, тестовані зміни
3. Тест-орієнтованість: Тести — це страхувальна сітка
4. Безперервність: Рефакторинг — постійний процес, а не одноразова подія
5. Співпраця: Затвердження користувача потрібне на кожній фазі

Огляд робочого процесу

Фаза 1: Дослідження та аналіз
    ↓
Фаза 2: Оцінка покриття тестами
    ↓
Фаза 3: Виявлення запахів коду
    ↓
Фаза 4: Створення плану рефакторингу
    ↓
Фаза 5: Інкрементальна реалізація
    ↓
Фаза 6: Перегляд та ітерація

---

Фаза 1: Дослідження та аналіз

Цілі

• Зрозуміти структуру та призначення кодової бази
• Визначити обсяг рефакторингу
• Зібрати контекст про бізнес-вимоги

Запитання до користувача

Перед початком уточніть:

1. Обсяг: Які файли/модулі/функції потребують рефакторингу?
2. Цілі: Які проблеми ви намагаєтесь вирішити? (читабельність, продуктивність, супровідність)
3. Обмеження: Чи є зони, які НЕ слід змінювати?
4. Тиск термінів: Чи блокує це іншу роботу?
5. Стан тестів: Чи існують тести? Чи проходять вони?

Дії

• Прочитати та зрозуміти цільовий код
• Виявити залежності та інтеграції
• Задокументувати поточну архітектуру
• Зафіксувати існуючі маркери технічного боргу (TODOs, FIXMEs)

Вивід

Представити знахідки користувачу:

• Резюме структури коду
• Виявлені проблемні зони
• Початкові рекомендації
• Запросити затвердження для продовження

---

Фаза 2: Оцінка покриття тестами

Чому тести важливі

«Рефакторинг без тестів — як їзда без пасків безпеки.» — Мартін Фаулер

Тести — ключовий засіб безпечного рефакторингу. Без них ви ризикуєте внести помилки.

Кроки оцінки

1. Перевірити наявні тести

   # Пошук файлів тестів
   find . -name "*test*" -o -name "*spec*" | head -20
   

2. Запустити існуючі тести

   # JavaScript/TypeScript
   npm test
   
   # Python
   pytest -v
   
   # Java
   mvn test
   

3. Перевірити покриття (якщо доступно)

   # JavaScript
   npm run test:coverage
   
   # Python
   pytest --cov=.
   

Точка рішення: Запитати користувача

Якщо тести існують та проходять:

• Перейти до Фази 3

Якщо тести відсутні або неповні: Представити варіанти:

1. Спочатку написати тести (рекомендовано)
2. Додавати тести інкрементально під час рефакторингу
3. Продовжити без тестів (ризиковано — потребує підтвердження користувача)

Якщо тести не проходять:

• ЗУПИНИТИСЯ. Виправити тести перед рефакторингом
• Запитати користувача: Чи слід спочатку виправити тести?

Рекомендації щодо написання тестів (якщо потрібно)

Для кожної функції, що рефакториться, забезпечити тести для:

• Успішний шлях (нормальна робота)
• Граничні випадки (порожні введення, null, межі)
• Сценарії помилок (невалідні введення, виключення)

Використовуйте цикл «red-green-refactor»:

1. Написати тест, що не проходить (red)
2. Зробити так, щоб пройшов (green)
3. Рефакторити

---

Фаза 3: Виявлення запахів коду

Що таке запахи коду?

Симптоми глибших проблем у коді. Це не помилки, а індикатори того, що код можна покращити.

Типові запахи коду для перевірки

Див. references/code-smells.md для повного каталогу.

Короткий довідник

Запах	Ознаки	Вплив
Довгий метод	Методи > 30-50 рядків	Важко зрозуміти, тестувати, супроводжувати
Дубльований код	Та сама логіка в кількох місцях	Виправлення помилок потрібне в кількох місцях
Великий клас	Клас з занадто багатьма відповідальностями	Порушує принцип єдиної відповідальності
Заздрість до функцій	Метод використовує дані іншого класу більше	Погана інкапсуляція
Одержимість примітивами	Надмірне використання примітивів замість обʼєктів	Відсутні доменні концепції
Довгий список параметрів	Методи з 4+ параметрами	Складно викликати правильно
Групи даних	Ті самі елементи даних зʼявляються разом	Відсутня абстракція
Оператори Switch	Складні ланцюжки switch/if-else	Важко розширювати
Спекулятивна загальність	Код «на всякий випадок»	Зайва складність
Мертвий код	Невикористаний код	Плутанина, тягар супровідності

Кроки аналізу

1. Автоматичний аналіз (якщо скрипти доступні)

   python scripts/detect-smells.py <file>
   

2. Ручний перегляд

   • Систематично пройти код
   • Зафіксувати кожен запах з розташуванням та серйозністю
   • Категоризувати за впливом (Критичний/Високий/Середній/Низький)

3. Пріоритезація Зосередитися на запахах, які:

   • Блокують поточну розробку
   • Спричиняють помилки або плутанину
   • Впливають на найчастіше змінювані шляхи коду

Вивід: Звіт про запахи

Представити користувачу:

• Список виявлених запахів з розташуванням
• Оцінку серйозності для кожного
• Рекомендований порядок пріоритету
• Запросити затвердження пріоритетів

---

Фаза 4: Створення плану рефакторингу

Вибір рефакторингів

Для кожного запаху обрати відповідний рефакторинг з каталогу.

Див. references/refactoring-catalog.md для повного списку.

Відповідність запахів рефакторингам

Запах коду	Рекомендований рефакторинг
Long Method	Extract Method, Replace Temp with Query
Duplicated Code	Extract Method, Pull Up Method, Form Template Method
Large Class	Extract Class, Extract Subclass
Feature Envy	Move Method, Move Field
Primitive Obsession	Replace Primitive with Object, Replace Type Code with Class
Long Parameter List	Introduce Parameter Object, Preserve Whole Object
Data Clumps	Extract Class, Introduce Parameter Object
Switch Statements	Replace Conditional with Polymorphism
Speculative Generality	Collapse Hierarchy, Inline Class, Remove Dead Code
Dead Code	Remove Dead Code

Структура плану

Використовуйте шаблон templates/refactoring-plan.md.

Для кожного рефакторингу:

1. Ціль: Який код зміниться
2. Запах: Яку проблему вирішує
3. Рефакторинг: Яку техніку застосувати
4. Кроки: Детальні мікрокроки
5. Ризики: Що може піти не так
6. Відкат: Як скасувати за потреби

Поетапний підхід

КРИТИЧНО: Впроваджуйте рефакторинг поступово, фазами.

Фаза A: Швидкі перемоги (Низький ризик, висока цінність)

• Перейменування змінних для ясності
• Витяг очевидного дубльованого коду
• Видалення мертвого коду

Фаза B: Структурні покращення (Середній ризик)

• Витяг методів з довгих функцій
• Введення обʼєктів параметрів
• Переміщення методів до відповідних класів

Фаза C: Архітектурні зміни (Вищий ризик)

• Заміна умовних конструкцій поліморфізмом
• Витяг класів
• Введення патернів проєктування

Точка рішення: Представити план користувачу

Перед реалізацією:

• Показати повний план рефакторингу
• Пояснити кожну фазу та її ризики
• Отримати явне затвердження для кожної фази
• Запитати: «Чи продовжити з Фазою A?»

---

Фаза 5: Інкрементальна реалізація

Золоте правило

«Зміна → Тест → Зелений? → Коміт → Наступний крок»

Ритм реалізації

Для кожного кроку рефакторингу:

1. Попередня перевірка

   • Тести проходять (зелені)
   • Код компілюється

2. Зробити ОДНУ малу зміну

   • Дотримуватися механіки з каталогу
   • Тримати зміни мінімальними

3. Верифікація

   • Негайно запустити тести
   • Перевірити на помилки компіляції

4. Якщо тести проходять (зелені)

   • Закомітити з описовим повідомленням
   • Перейти до наступного кроку

5. Якщо тести не проходять (червоні)

   • ЗУПИНИТИСЯ негайно
   • Скасувати зміну
   • Проаналізувати, що пішло не так
   • Запитати користувача, якщо незрозуміло

Стратегія комітів

Кожен коміт має бути:

• Атомарний: Одна логічна зміна
• Оборотний: Легко відкатити
• Описовий: Зрозуміле повідомлення коміту

Приклади повідомлень комітів:

refactor: Extract calculateTotal() from processOrder()
refactor: Rename 'x' to 'customerCount' for clarity
refactor: Remove unused validateOldFormat() method

Звіт про прогрес

Після кожної підфази звітувати користувачу:

• Внесені зміни
• Тести досі проходять?
• Виявлені проблеми
• Запитати: «Продовжити з наступною порцією?»

---

Фаза 6: Перегляд та ітерація

Контрольний список після рефакторингу

• Усі тести проходять
• Немає нових попереджень/помилок
• Код успішно компілюється
• Поведінка не змінилася (ручна верифікація)
• Документація оновлена за потреби
• Історія комітів чиста

Порівняння метрик

Запустити аналіз складності до і після:

python scripts/analyze-complexity.py <file>

Представити покращення:

• Зміна кількості рядків коду
• Зміна цикломатичної складності
• Зміна індексу супровідності

Перегляд користувачем

Представити фінальні результати:

• Резюме всіх змін
• Порівняння коду до/після
• Покращення метрик
• Залишковий технічний борг
• Запитати: «Чи задоволені ви цими змінами?»

Наступні кроки

Обговорити з користувачем:

• Додаткові запахи для усунення?
• Запланувати подальший рефакторинг?
• Застосувати аналогічні зміни в інших місцях?

---

Важливі рекомендації

Коли ЗУПИНИТИСЯ та запитати

Завжди паузу та консультацію з користувачем, коли:

• Невпевненість щодо бізнес-логіки
• Зміна може вплинути на зовнішні API
• Покриття тестами недостатнє
• Потрібне значне архітектурне рішення
• Рівень ризику зростає
• Зустрічаєте неочікувану складність

Правила безпеки

1. Ніколи не рефакторити без тестів (якщо користувач явно не підтвердив ризик)
2. Ніколи не робити великих змін — розбивати на крихітні кроки
3. Ніколи не пропускати запуск тестів після кожної зміни
4. Ніколи не продовжувати, якщо тести не проходять — виправити або відкатити
5. Ніколи не припускати — якщо сумніваєтесь, запитайте

Чого НЕ робити

• Не поєднуйте рефакторинг з додаванням функцій
• Не рефакторте під час аварій на продакшні
• Не рефакторте код, який не розумієте
• Не переускладнюйте — тримайте просто
• Не рефакторте все одразу

---

Приклад швидкого старту

Сценарій: Довгий метод з дублюванням

До:

function processOrder(order) {
  // 150 рядків коду з:
  // - Дубльованою логікою валідації
  // - Інлайн-обчисленнями
  // - Змішаними відповідальностями
}

Кроки рефакторингу:

1. Переконатися, що тести існують для processOrder()
2. Витягти валідацію у validateOrder()
3. Тест — має пройти
4. Витягти обчислення у calculateOrderTotal()
5. Тест — має пройти
6. Витягти сповіщення у notifyCustomer()
7. Тест — має пройти
8. Перегляд — processOrder() тепер оркеструє 3 чіткі функції

Після:

function processOrder(order) {
  validateOrder(order);
  const total = calculateOrderTotal(order);
  notifyCustomer(order, total);
  return { order, total };
}

---

Довідники

• Каталог запахів коду — повний список запахів коду
• Каталог рефакторингів — техніки рефакторингу
• Шаблон плану рефакторингу — шаблон планування

Скрипти

• scripts/analyze-complexity.py — аналіз метрик складності коду
• scripts/detect-smells.py — автоматичне виявлення запахів

Історія версій

• v1.0.0 (2025-01-15): Початковий випуск з методологією Фаулера, поетапним підходом, точками консультації з користувачем