Комментарии и стиль кода

Комментарии — это заметки для людей, а не для компьютера. А стиль кода — это как хороший почерк: без него можно писать, но читать будет мучительно. Разберёмся, как писать чистый, читаемый код.

💬 Однострочные комментарии

Однострочный комментарий начинается с //. Всё, что идёт после // до конца строки, компилятор полностью игнорирует. Это как записка на полях учебника — она не влияет на содержание, но помогает понять.

// Это комментарий — компилятор его не видит
int age = 25;  // Можно писать комментарий после кода
// Можно написать несколько строк подряд:
// Первая строка
// Вторая строка
System.out.println(age); // Выведет 25

Однострочные комментарии — самый частый вид комментариев. Используйте их для:

• Пояснения сложной логики: // Проверяем, что пользователь старше 18 лет
• Временной пометки: // TODO: добавить валидацию
• Отключения строки: // System.out.println("отладка");

📝 Многострочные комментарии

Многострочный комментарий оборачивается в /* и */. Он может занимать сколько угодно строк:

/*
 * Это многострочный комментарий.
 * Он может занимать несколько строк.
 * Полезен для длинных описаний.
 */
int count = 0;

На практике многострочные комментарии используются реже однострочных. Они удобны, когда нужно написать длинное описание, но в современном коде их место занимают Javadoc-комментарии.

📚 Javadoc-комментарии

Javadoc-комментарий начинается с /** и используется для автоматической генерации документации. Он описывает назначение классов, методов и полей:

/**
 * Вычисляет факториал числа n.
 * Факториал числа n — это произведение всех натуральных
 * чисел от 1 до n включительно.
 *
 * @param n неотрицательное целое число
 * @return факториал числа n
 */
public static long factorial(int n) {
    long result = 1;
    for (int i = 2; i <= n; i++) {
        result *= i;
    }
    return result;
}

Специальные теги внутри Javadoc:

• @param — описание параметра метода
• @return — описание возвращаемого значения
• @throws — описывает, какие исключения может выбросить метод
• @author — автор метода/класса
• @since — версия, с которой доступен метод

IntelliJ IDEA умеет автоматически генерировать Javadoc. Наведите курсор на метод, нажмите Alt+Enter и выберите "Add Javadoc".

✨ Форматирование кода

Хороший код — читаемый код. Вот основные правила форматирования, которых придерживаются в Java:

Отступы

Используйте 4 пробела для каждого уровня вложенности. Не табуляцию (tab), а именно пробелы — так код одинаково выглядит на всех компьютерах:

public class Example {
    public static void main(String[] args) {
        int x = 10;
        if (x > 5) {
            System.out.println("Больше пяти");
            if (x > 8) {
                System.out.println("Больше восьми");
            }
        }
    }
}

Пробелы

Пробелы делают код визуально раздельным:

// Правильно:
int x = 10;
if (x > 5) { }
for (int i = 0; i < 10; i++) { }
System.out.println("Привет");

// Неправильно:
int x=10;
if(x>5){}
for(int i=0;i<10;i++){ }
System.out.println("Привет");

Фигурные скобки

В Java принят стиль фигурных скобок K&R (Kernighan & Ritchie): открывающая скобка — на той же строке, закрывающая — на отдельной:

// Правильно (K&R стиль):
if (condition) {
    doSomething();
} else {
    doOther();
}

// Неправильно (Allman стиль — не для Java):
if (condition)
{
    doSomething();
}
else
{
    doOther();
}

Пустые строки

Используйте пустые строки для разделения логических блоков кода. Одна пустая строка между методами, две — между классами:

public class Calculator {

    public int add(int a, int b) {
        return a + b;
    }

    public int subtract(int a, int b) {
        return a - b;
    }

    public int multiply(int a, int b) {
        return a * b;
    }
}

⚙️ Code style в IntelliJ IDEA

IntelliJ IDEA умеет автоматически форматировать код. Это огромная экономия времени:

• Ctrl+Alt+L (Cmd+Alt+L на Mac) — автоматическое форматирование всего файла
• Ctrl+Alt+O — удаление неиспользуемых импортов
• Ctrl+Shift+Space — умное автодополнение
• Alt+Enter — предложения по улучшению кода

Настройте автоматическое форматирование при сохранении: Settings → Tools → Actions on Save → Reformat code.

IntelliJ также поддерживает стандартные стили кодирования:

• Google Java Style — рекомендуется Google, 2 пробела для отступов
• Oracle Java Style — стандарт Oracle, 4 пробела
• IntelliJ Default — стиль по умолчанию для IntelliJ

🏆 Почему чистый код важен

Чистый код — это не прихоть, а необходимость. Вот почему:

✅ Итоги урока

• // — однострочный комментарий, /* */ — многострочный, /** */ — Javadoc
• Комментируйте ПОЧЕМУ, а не ЧТО делает код
• 4 пробела для отступов, K&R стиль для скобок, пробелы вокруг операторов
• Ctrl+Alt+L — автоформатирование в IntelliJ IDEA
• Чистый код = читаемый код = меньше ошибок = экономия времени
• Пустые строки разделяют логические блоки

Модуль 1 завершён! Теперь вы знаете основы Java. Следующий модуль: Примитивные типы и операции →