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

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

В этой главе рассматривается синтаксис всех трёх стилей, способы генерации HTML-документации из Javadoc, а также — что не менее важно — когда комментарий стоит писать, а когда он лишь добавляет шум. Если вы только начинаете знакомиться со структурой Java, сначала прочитайте Java Syntax.

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

Всё, что идёт после // до конца строки, является комментарием:

int total = price * quantity;   // running subtotal in cents
// totalPrice was renamed to total in 2024-05

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

Многострочные комментарии — /* ... */

Всё, что находится между /* и */, игнорируется, даже если занимает несколько строк:

/*
 * The default leading-asterisk style isn't required, but most IDEs
 * insert it automatically and it keeps long comments readable.
 *
 * This block is parsed as a single comment.
 */
int retries = 3;

Многострочные комментарии также можно использовать внутри строки:

int width = 800 /* pixels */;

Вложенные комментарии недопустимы: /* outer /* inner */ */ заканчивается на первом */, оставляя лишние символы */, которые вызовут ошибку компиляции. Чтобы «закомментировать» блок, уже содержащий /* … */, используйте // на каждой строке (в вашей IDE для этого есть горячая клавиша — обычно Ctrl+/ / Cmd+/).

Javadoc-комментарии — /** ... */

Javadoc-комментарии начинаются с /** (обратите внимание: две звёздочки) и обрабатываются инструментом javadoc для генерации HTML-документации:

/**
 * Calculates the area of a rectangle.
 *
 * @param width  the rectangle's width in cm; must be non-negative
 * @param height the rectangle's height in cm; must be non-negative
 * @return the area in square centimeters
 */
public static double area(double width, double height) {
    return width * height;
}

Javadoc-комментарии размещаются непосредственно перед классом, методом или полем, которые они описывают. Первое предложение становится строкой краткого описания в сгенерированной документации.

Наиболее полезные теги:

• @param name description — по одному на каждый параметр
• @return description — что возвращает метод
• @throws ExceptionClass description — когда метод выбрасывает исключение
• @see ClassOrLink — перекрёстная ссылка
• @since 1.5 — начиная с какой версии API добавлен
• @deprecated reason — помечает как устаревший (компилятор также выдаёт предупреждение)

Вся стандартная библиотека документирована с помощью Javadoc; IDE читают её для отображения подсказок.

Генерация HTML-документации

Инструмент javadoc поставляется вместе с JDK. Укажите ему путь к исходным файлам (или пакетам), и он создаст просматриваемый HTML-сайт:

javadoc -d docs Greeter.java

Флаг -d docs задаёт выходную директорию. Откройте docs/index.html в браузере, чтобы увидеть сгенерированные страницы — тот же формат, что и в официальной документации Oracle API, построенный на основе комментариев над каждым классом и методом.

Когда писать комментарии, а когда нет

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

// BAD: increment counter
counter++;

// BAD: returns the user's name
public String getName() { return name; }

Комментарии оправдывают своё место, когда объясняют почему, а не что:

// Stripe rejects amounts smaller than $0.50 — round up so we never
// hit the minimum-charge error.
int chargeCents = Math.max(50, computed);

Или когда документируют неочевидное ограничение:

// Caller must hold the writeLock; this method itself does no locking.
private void persist(Order o) { ... }

Для публичных API пишите Javadoc. Для внутреннего кода пишите только те комментарии, которые помогут следующему читателю принять решение.

Демонстрация

Компилятор удаляет все три стиля комментариев перед генерацией байткода, поэтому они не несут никаких затрат во время выполнения.

Что дальше

Теперь, когда вы умеете документировать код, переходите к строительным блокам, которые он описывает:

• Java Variables — объявление, инициализация и область видимости.
• Java Syntax — операторы, блоки и правила, которые enforces компилятор.
• Java Hello World — минимальная программа, внутри которой живут ваши комментарии.

Практика