Комментарии в Java: однострочные, многострочные и Javadoc

Зачем нужны комментарии

Комментарий — это текст в исходном коде, который компилятор Java полностью игнорирует. Он никогда не становится частью работающей программы — он существует исключительно для людей, читающих код. Комментарии используют, чтобы объяснить, почему что-то сделано определённым образом, оставить напоминания или временно отключить код, не удаляя его.

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

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

Две косые черты (//) начинают комментарий, который продолжается до конца текущей строки. Компилятор пропускает всё от // до перевода строки.

public class Main {
    public static void main(String[] args) {
        // Вывести приветствие в консоль
        System.out.println("Hello, Java!");

        int score = 90; // комментарий также может стоять после кода
        System.out.println(score);
    }
}

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

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

Когда ваша заметка занимает несколько строк, блочный комментарий аккуратнее, чем добавлять // к каждой строке. Блочный комментарий начинается с /* и заканчивается */. Всё между ними — сколько бы строк там ни было — игнорируется.

public class Main {
    public static void main(String[] args) {
        /*
         * Эта программа показывает блочный комментарий.
         * Звёздочки в начале каждой строки — это лишь
         * соглашение для читаемости, они не обязательны.
         */
        System.out.println("Block comments are handy.");
    }
}

Выровненные по левому краю символы * — это стилевое соглашение, а не правило. Единственное, что действительно важно, — это открывающий /* и закрывающий */.

Закомментировать код

Комментарии — стандартный способ отключить код во время экспериментов, не удаляя его. Используйте // для одной строки или блочный комментарий, чтобы отключить сразу несколько строк.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

Запустите код, и вы увидите, что выводятся только две строки «runs». Закомментированные вызовы println невидимы для компилятора.

Частая ловушка: блочные комментарии не вкладываются друг в друга. Первый же */ закрывает комментарий, сколько бы /* ни стояло перед ним. Поэтому нельзя вложить блок /* ... */ внутрь другого блока /* ... */ — внутренний */ завершает весь комментарий, а остаток превращается в синтаксическую ошибку. Если нужно отключить участок, который уже содержит блочные комментарии, используйте // на каждой строке (большинство редакторов делают это одним сочетанием клавиш).

Документирующие комментарии Javadoc

Комментарий Javadoc похож на блочный, но начинается с /** — двух звёздочек. Он предназначен для документирования класса, метода или поля и располагается прямо над тем, что описывает. Инструмент javadoc превращает их в просматриваемую HTML-документацию API, а IDE показывают их во всплывающих подсказках при наведении.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

Теги @param, @return и @throws — это структурированные поля, понятные инструментам. Для компилятора это по-прежнему просто игнорируемый комментарий — его ценность целиком в документации, которую он порождает, и в подсказках, которые IDE даёт другим разработчикам (и вам самим полгода спустя).

Хорошие комментарии и шум

Комментарий должен объяснять то, чего код не может сказать сам по себе. Комментарии, которые лишь повторяют код, создают беспорядок и со временем устаревают по мере изменения кода.

// Плохо: просто повторяет то, что код и так очевидно делает
int i = i + 1; // прибавить единицу к i

// Лучше: объясняет причину, которую код показать не может
retries++; // отступить и повторить; у API лимит 5 запросов/сек

Стремитесь сделать код читаемым за счёт понятных имён и структуры, а комментарии приберегайте для почему: намерения, компромиссы, граничные случаи и ссылки на контекст. Если вы ловите себя на том, что пишете комментарий, объясняющий запутанную строку, это часто знак, что вместо этого стоит переименовать переменную или выделить метод.

Далее: Переменные

Теперь, когда вы умеете снабжать код пометками, следующий строительный блок — хранение в нём данных. На следующей странице рассматриваются переменные: как их объявлять, какие типы они содержат и какие правила Java навязывает, поскольку язык статически типизирован.