Ці правила спрямовують генерацію коду для створення підтримуваного, професійної якості коду.

Змістовні назви

• Використовуйте назви, що розкривають намір та пояснюють чому щось існує
• Уникайте дезінформації та безглуздих розрізнень (напр., 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