mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-09-22 01:10:42 +02:00
i18n(uk): add missing root files (CLAUDE.md, clean-code-rules, resources, etc.)
- 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
This commit is contained in:
@@ -0,0 +1,115 @@
|
||||
<!-- 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
|
||||
Reference in New Issue
Block a user