3f11521fcc
- Translate CLAUDE.md, clean-code-rules.md, resources.md - Translate pr-review plugin (README, commands, agents) - Translate documentation templates (ADR, api-endpoint, function-docs) - Copy RELEASE_NOTES.md, LICENSE, claude-howto-logo.png as-is - Update TRANSLATION_QUEUE.md to 100% Ref: luongnv89/claude-howto#63
116 lines
8.6 KiB
Markdown
116 lines
8.6 KiB
Markdown
<!-- 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
|