Стиль і читабельність коду, Code Conventions

1. Вступ

У програмуванні стиль — це не про моду, а про виживання. Java — мова, якою користуються великі команди, і якщо кожен писатиме «як звик», то проєкт швидко перетвориться на набір розрізнених фрагментів, у яких розібратися зможе лише автор (і то не завжди).

Стиль коду — це набір правил, які роблять код однаково читабельним для всіх. Це як дорожні знаки: якщо їх ігнорувати, рух швидко перетвориться на хаос.

Чому це важливо?

• Читабельність: код читають частіше, ніж пишуть. Поганий стиль — як поганий почерк у лікаря: ніхто не зрозуміє, що там написано.
• Підтримуваність: якщо код написано за правилами, його простіше змінювати, менша ймовірність випадково щось зламати.
• Спільна робота: у команді всі мають розуміти одне одного без зайвих запитань.
• Інструменти: автоформатувачі та аналізатори коду працюють краще, якщо стиль єдиний.

2. Основні помилки стилю коду (і як їх уникати)

Недотримання відступів і дужок

Помилка:
Код без відступів і з хаотичними дужками — мука для очей і мозку.

if(x>0){
System.out.println("x додатний");
}else{
System.out.println("x не додатний");
}

Як треба:

if (x > 0) {
    System.out.println("x додатний");
} else {
    System.out.println("x не додатний");
}

Коментар:
Використовуйте чотири пробіли для кожного рівня вкладеності (це стандарт Java). Табуляції варто уникати, якщо тільки вся команда не домовилася інакше.

Некоректні імена змінних, методів і класів

Помилка:

int a = 5;
String s = "Вася";
void f() { /* ... */ }

Як треба:

int age = 5;
String userName = "Василь";
void printReport() { /* ... */ }

Коментар:
Назви мають бути змістовними й відображати суть змінної або методу.

• Класи — з великої літери, CamelCase: UserAccount.
• Методи й змінні — з малої літери, camelCase: calculateSalary, userList.

Надто довгі методи й класи

Помилка:
Метод на 100 рядків, клас на 1000 рядків — справжній кошмар для підтримки.

Як треба:
Кожен метод має робити щось одне й бути коротким (ідеально — вміщуватися на один екран). Класи теж не мають розростатися до розмірів «Війни і миру».

Приклад:

Погано:

public void processOrder() {
    // 200 рядків коду
}

Добре:

public void processOrder() {
    validateOrder();
    calculateTotal();
    saveToDatabase();
    sendEmailConfirmation();
}

Використання «магічних чисел» і рядків

Помилка:

if (status == 42) {
    // ...
}

Як треба:

public static final int STATUS_APPROVED = 42;

if (status == STATUS_APPROVED) {
    // ...
}

Коментар:
Замість «магічних» чисел і рядків використовуйте константи (static final). У нових версіях Java для цього є ще й enum — використовуйте їх для обмежених наборів значень.

Коментарі: відсутність або надмірність

Помилка 1:
Немає коментарів взагалі — незрозуміло, що робить складний код.

Помилка 2:
Коментарі до кожної дії, навіть очевидної.

// Збільшуємо x на 1
x = x + 1;

// Перевіряємо, чи дорівнює x 10
if (x == 10) {
    // ...
}

Такі коментарі лише заважають! Коментуйте тільки складні або неочевидні моменти. А взагалі, хороший код має бути зрозумілим без коментарів — коментарі потрібні для пояснення «чому», а не «що».

// Враховуємо знижку для VIP-клієнтів
double total = calculateTotalWithDiscount();

3. Конвенції Java: як пишуть професіонали

У Java є офіційні та де-факто стандарти оформлення коду. Oracle Java Code Conventions і Google Java Style Guide — найпопулярніші.

Відступи та дужки

Відкривна фігурна дужка ставиться в тому самому рядку, що й оголошення:

public void print() {
    // ...
}

Вкладеність — чотири пробіли.

Іменування

• Класи й інтерфейси: CamelCase з великої літери (Person, UserAccount).
• Методи й змінні: camelCase з малої (calculateSalary, userList).
• Константи: УСІ_ВЕЛИКІ_ЛІТЕРИ_З_ПІДКРЕСЛЕННЯМ (MAX_SIZE, DEFAULT_TIMEOUT).
• Пакети: лише малі літери, розділені крапками (com.example.project).

Пробіли

Пробіли навколо операторів і після коми:

int sum = a + b;
System.out.println(name, age);

Не ставте пробіл після відкривної та перед закривною дужкою:

if (x > 0) { ... }

Довжина рядка

Рекомендовано не перевищувати 100–120 символів у рядку. Так‑так, у вас може бути величезний монітор, але код усе одно краще читається, коли він не тікає за горизонт.

Порядок оголошення членів класу

Рекомендований порядок (за Oracle):

1. Поля (спочатку статичні, потім звичайні)
2. Конструктори
3. Методи

Приклад:

public class User {
    private static int userCount;
    private String name;

    public User(String name) {
        this.name = name;
        userCount++;
    }

    public String getName() {
        return name;
    }
}

4. Приклад: рефакторинг поганого стилю

Ось приклад класу, який можна зустріти у дикій природі:

class person{String n;int a;void p(){System.out.println(n+" "+a);}}

Десь в офісі через цей код плаче один Java‑розробник.

Давайте поліпшимо його:

public class Person {
    private String name;
    private int age;

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public void print() {
        System.out.println(name + " " + age);
    }
}

Що змінилося:

• Клас і члени з правильними модифікаторами доступу.
• Назви змістовні, читабельні.
• Кожен член класу — з нового рядка.
• Використовується конструктор для ініціалізації.
• Поля private, щоб дотриматися інкапсуляції.

5. Корисні нюанси

Автоматичне форматування

Сучасні IDE (IntelliJ IDEA, Eclipse, VS Code) вміють автоматично форматувати код за стандартом.

Гарячі клавіші:

• IntelliJ IDEA: Ctrl + Alt + L
• Eclipse: Ctrl + Shift + F

Статичний аналіз

Інструменти на кшталт Checkstyle, SonarLint, PMD допомагають виявляти порушення стилю та потенційні помилки ще до запуску програми.

Як це виглядає:

• Checkstyle сваритиметься, якщо у вас змінна називається x замість userAge.
• SonarLint підкаже, якщо метод надто довгий або клас порушує принципи SOLID.

Розподіл відповідальності та «чистий» код

• Кожен клас має відповідати лише за одне завдання (Single Responsibility Principle).
• Не бійтеся створювати додаткові класи й методи — це не «роздування», а турбота про майбутнього читача.
• Намагайтеся уникати дублювання коду: якщо бачите два схожі фрагменти — винесіть їх в окремий метод.

Константи та «магічні числа»: як правильно

Замість:

double price = 100 * 0.18;

Краще:

public static final double VAT_RATE = 0.18;
double price = 100 * VAT_RATE;

А якщо у вас часто трапляються фіксовані набори значень — використовуйте enum:

public enum Status {
    NEW, IN_PROGRESS, DONE
}

6. Типові помилки в стилі та читабельності коду

Помилка № 1: Ігнорування Code Conventions.
Якщо в команді немає єдиного стилю, код швидко стає нечитабельним і складним для підтримки. Навіть якщо ви пишете наодинці, за рік ви самі скажете собі дякую.

Помилка № 2: Надто короткі/довгі назви.
Змінна a або temp — погано. Змінна theCurrentUserNameThatIsUsedForAuthorizationInTheSystem — теж не варто. Знайдіть баланс: userName, age, bookList.

Помилка № 3: «Магічні числа».
Вставка чисел і рядків прямо в код заважає підтримці та збільшує ймовірність помилок.

Помилка № 4: Величезні методи й класи.
Що більший метод — то складніше його тестувати й розуміти. Розбивайте на логічні частини.

Помилка № 5: Погана структура класу.
Поля розкидані де завгодно, методи оголошено у випадковому порядку — усе це заважає швидко знайти потрібне місце.

Помилка № 6: Надмірні або відсутні коментарі.
Коментар «ініціалізація змінної» поруч із int x = 0; не потрібен. Коментар, що пояснює складну бізнес-логіку, — дуже потрібен.

Помилка № 7: Неузгоджене форматування.
В одній частині проєкту — чотири пробіли, в іншій — табуляція; тут дужки — з нового рядка, там — у тому самому рядку. Це виглядає неохайно й дратує колег.