mirror of https://fastgit.cc/github.com/luongnv89/claude-howto synced 2026-04-20 21:00:14 +08:00

Files

Evgenij I 3f11521fcc 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

2026-04-10 00:34:08 +03:00

8.6 KiB

Raw Permalink Blame History

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

8.6 KiB Raw Permalink Blame History Unescape Escape