Комментарии в Java

Комментарии — это фрагменты исходного кода, которые компилятор полностью игнорирует. Они нужны людям, читающим программу: автору через полгода и коллегам в команде. В Java три вида комментариев: однострочные //, многострочные /* ... */ и документирующие /** ... */ (Javadoc).

Хороший комментарий объясняет «почему», а не «что». «Что» обычно видно из самого кода: i++ — это инкремент, дополнительно подписывать его не нужно. А вот «почему мы здесь делаем именно +1, а не +2» — уже полезно.

Javadoc-комментарии играют особую роль: специальный инструмент javadoc собирает их в HTML-документацию, которую вы видите на сайте Oracle для стандартной библиотеки.

Зачем это нужно

  • Объяснить намерения, ограничения и подводные камни кода.

  • Сгенерировать API-документацию автоматически (Javadoc).

  • Временно «отключить» блок кода при отладке.

  • Передать сопровождающим контекст: ссылки на тикеты, обоснования формул, источники.

Пример 1. Однострочный комментарий

public class SingleLineComment {
    public static void main(String[] args) {
        // Это однострочный комментарий — он действует до конца строки.
        int pin = 13; // Светодиод на Arduino Uno
        System.out.println("Pin = " + pin);
    }
}

Вывод:

Pin = 13

Всё после // и до перевода строки — комментарий. Можно ставить как на отдельной строке, так и в конце инструкции.

Пример 2. Многострочный комментарий

public class BlockComment {
    public static void main(String[] args) {
        /*
         * Этот блок описывает алгоритм:
         * 1. Считать температуру с датчика.
         * 2. Если > 30 — включить вентилятор.
         * 3. Иначе — выключить.
         */
        double temperature = 32.5;
        System.out.println("Температура: " + temperature);
    }
}

Вывод:

Температура: 32.5

Многострочный комментарий начинается с /* и заканчивается */. Звёздочки в начале строк — лишь общепринятый стиль оформления, компилятор их не требует.

Пример 3. Javadoc-комментарий

/**
 * Утилитный класс для управления мотором Robot Phobo.
 *
 * @author  AlashEd
 * @version 1.0
 */
public class MotorUtils {

    /**
     * Преобразует процент мощности в PWM-значение для analogWrite.
     *
     * @param percent мощность в диапазоне 0..100
     * @return PWM-значение 0..255
     */
    public static int percentToPwm(int percent) {
        return (int) Math.round(percent * 255.0 / 100.0);
    }

    public static void main(String[] args) {
        System.out.println(percentToPwm(50));
        System.out.println(percentToPwm(100));
    }
}

Вывод:

128
255

Javadoc начинается с /** (двух звёздочек). Теги @param, @return, @author и т. д. распознаются инструментом javadoc и попадают в сгенерированный HTML.

Пример 4. Отключение кода через комментарий

public class CommentOut {
    public static void main(String[] args) {
        int a = 10;
        int b = 20;
        // int c = a + b;   // временно убрали, проверяем без c
        System.out.println(a);
        System.out.println(b);
    }
}

Вывод:

10
20

Часто используется в отладке: закомментировали строку, проверили поведение, потом вернули обратно.

Пример 5. Документирование класса целиком

/**
 * Класс <code>LedBlinker</code> мигает виртуальным светодиодом
 * заданное число раз с указанным интервалом.
 *
 * <p>Пример использования:
 * <pre>
 *     LedBlinker.blink(5, 500);
 * </pre>
 */
public class LedBlinker {
    /**
     * Мигнуть N раз.
     *
     * @param times    сколько раз
     * @param delayMs  пауза между миганиями, мс
     */
    public static void blink(int times, int delayMs) {
        for (int i = 1; i <= times; i++) {
            System.out.println("LED ON  #" + i);
            System.out.println("LED OFF #" + i);
        }
    }

    public static void main(String[] args) {
        blink(2, 100);
    }
}

Вывод:

LED ON  #1
LED OFF #1
LED ON  #2
LED OFF #2

Внутри Javadoc разрешены HTML-теги: <code>, <pre>, <p>, <b> и др.

Пример 6. TODO и FIXME

public class TodoExample {
    public static void main(String[] args) {
        int distance = readUltrasonic();
        System.out.println("Расстояние: " + distance + " см");
    }

    // TODO: реализовать опрос реального датчика HC-SR04
    // FIXME: при distance == 0 нужно вернуть ошибку, а не 0
    static int readUltrasonic() {
        return 25;
    }
}

Вывод:

Расстояние: 25 см

IDE (IntelliJ, Eclipse, VS Code) подсвечивают теги TODO и FIXME и собирают их в отдельную панель.

Пример 7. Комментарии в выражениях

public class InlineBlockComment {
    public static void main(String[] args) {
        int total = 10 + /* налог */ 2 + /* доставка */ 5;
        System.out.println(total);
    }
}

Вывод:

17

Многострочный комментарий /* */ можно вставлять прямо в середину выражения. С однострочным // так не получится — он съест всё до конца строки.

Подводные камни

Предупреждение

  • Вложенные ``/* */`` запрещены: /* a /* b */ c */ — синтаксическая ошибка, второй */ закроет первый блок, а c */ станет невалидным кодом.

  • Закомментированные импорты и переменные копятся как мусор — лучше удалить, история сохранится в Git.

  • Комментарий не заменяет хороший код: если функции нужен большой комментарий, чтобы её понять, — возможно, её стоит разбить.

  • Javadoc-теги имеют синтаксис: @param без имени параметра или @return для void-метода вызовут предупреждения при сборке.

  • Не оставляйте устаревшие комментарии: «возвращает true/false» рядом с методом, который теперь возвращает int, дезориентирует сильнее, чем отсутствие комментария.

См. также

Примечание

Лицензия и источники

Техническое описание адаптировано из официальной документации Oracle Java Tutorials (https://docs.oracle.com/javase/tutorial/), Oracle Free Documentation License. Перевод на русский, примеры и пояснения — © AlashEd Wiki.