Комментарии в Java: не всё так просто

Если нужен короткий ответ: комментарий это текст, который компилятор пропускает мимо, а человек читает. В Java его пишут тремя способами: // до конца строки, /* ... */ блоком и /** ... */ для документации, из которой утилита javadoc потом собирает HTML-справочник.

Кратко

• Комментарии нужны людям, а не программе: компилятор их отбрасывает, в .class-файл они не попадают.
• Синтаксиса три: // для одной строки, /* */ для блока и /** */ для документирующего комментария JavaDoc.
• По назначению комментарии делят на два вида: комментарии реализации, которые объясняют код, и документирующие, которые описывают публичный API.
• Из JavaDoc-комментариев утилита javadoc собирает HTML-документацию, а IDE показывает их во всплывающих подсказках.
• Метки TODO и FIXME IDE собирает в отдельную панель, так что ими удобно вести список задач прямо в коде.
• Главное правило: объяснять надо «почему», а не «что». Если код требует пояснения, что он делает, чаще всего его стоит переписать.

Вступление

Комментарии: казалось бы, что может быть проще, и чего тут целую статью писать. Но тут не все так просто. Как говорил мой начальник, код писать может каждый, а вот хороший комментарий написать сложно. Большинство курсов по изучению языка начинаются с традиционного Hello World. Даже в Oracle Tutorials в разделе «Getting Started» мы начинаем с The "Hello World!" Application. И с самых первых строк кода мы видим их: Java комментарии. Их важность также подчеркивается тем, что в таком важном документе, как «Java Code Convention» комментариям отводится отдельный раздел: Comments.Как гласит документация, комментарии в Java делятся на два типа:

• комментарий реализации (или комментарий кода);
• документирующий комментарий.

Комментарии кода используются для описания отдельных строк/блоков, а комментарии для документирования используются, чтобы описать спецификацию кода (его интерфейс), не зависящую от его реализации. А по синтаксису комментарии различаются так. Java комментарии игнорируются компилятором, т.к. они несут смысл для разработчика, а не для пользователя. Поэтому на размер и скорость скомпилированной программы они не влияют вообще.

Комментарии Java кода

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

• Строчные (т.е. описываются в одну строку)

  // Строчный комментарий
  System.out.println("Hello, World!");

• Блочные (т.е. описываются целым блоком, т.к. не помещаются в одну строку)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

Интересной особенностью блочного комментария является то, что если мы начнем его с «/*-» (т.е. добавим после астериска минус), то текст данного блочного комментария отформатирован не будет.

Современные возможности IDE

Интересно, но при помощи определенных комментариев можно дать некоторым IDE подсказки. Например: В IntelliJ IDEA:

// TODO: Добавить валидацию входных данных
// FIXME: Исправить утечку памяти в этом методе
// NOTE: Этот алгоритм работает только для положительных чисел
// @formatter:off - отключает форматирование

В Eclipse:

//@formatter:on
//@formatter:off

В VSCode с расширениями для Java:

// HACK: Временное решение, требует рефакторинга
// XXX: Проблемный участок кода

AI-помощники и комментарии в 2025

Современные AI-помощники, такие как GitHub Copilot, JetBrains AI Assistant, и ChatGPT, могут: 1. Автоматически генерировать комментарии:

public int calculateFibonacci(int n) {
    // AI может предложить: "Calculates the nth Fibonacci number using iterative approach"
    if (n <= 1) return n;

    int prev = 0, curr = 1;
    for (int i = 2; i <= n; i++) {
        int temp = prev + curr;
        prev = curr;
        curr = temp;
    }
    return curr;
}

2. Проверять качество существующих комментариев и предлагать улучшения 3. Переводить комментарии на разные языки для международных команд

Современные принципы комментирования в 2025

1. Минимализм и осмысленность: Современная практика придерживается принципа "комментируй WHY, а не WHAT":

   // Плохо: комментарий пересказывает код
   // увеличиваем счетчик на единицу
   attempts++;
   
   // Хорошо: комментарий объясняет причину
   // провайдер нумерует попытки с единицы, поэтому нулевая нам не подходит
   attempts++;

2. Принцип Clean Code: Как говорил Роберт Мартин в "Чистый код": "Не комментируйте плохой код, перепишите его". В 2025 году этот принцип стал еще актуальнее
3. Google Java Style Guide: у Google есть открытый гайд по стилю Java, комментариям там отведен раздел 7 «Javadoc». Главное правило оттуда: как минимум JavaDoc должен быть у каждого видимого извне класса и члена класса, то есть у публичного класса верхнего уровня и у его public- и protected-членов.
4. Контекстные комментарии для бизнес-логики: В 2025 году особое внимание уделяется объяснению бизнес-контекста

Использовать комментарии нужно размеренно и только там, где это необходимо. Есть отличная книга "Чистый код: создание, анализ и рефакторинг", которую написал Роберт Мартин. В ней есть отдельная глава «Комментарии». В качестве эпиграфа к этой главе стоит не менее отличная цитата: «Не комментируйте плохой код, перепишите его» от Брайана У. Кернигана и П. Дж. Плауэра. С данной главой можно ознакомиться на Google Books. Общий смысл можно выразить в одной его цитате:

«Каждый раз, когда вы пишете комментарий, поморщитесь и ощутите свою неудачу»

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

Специальные комментарии TODO в современных IDE

В этой же главе упоминаются необычные комментарии, TODO:

// TODO: Добавить World
System.out.println("Hello, ");

Смысл в них в том, что они могут особым образом обрабатываться в IDE. Например, в IDEA они собираются на отдельной вкладке, где их можно посмотреть: И небольшой puzzler с комментарием:

public static void main(String[] args) {
    http://google.com
    System.out.println("Hello, World!");
}

Строка «http://google.com» является корректной строчкой внутри метода, т.к. http здесь это на самом деле метка, а дальше идет комментарий. Зачастую многие комментарии могут стать из комментариев кода комментарием для документирования, о которых поговорим далее.

Комментарии для документирования

Комментарии для документации описывают общедоступный API. API это программный интерфейс приложения, то есть те классы и методы, которые доступны другим разработчикам для выполнения каких-либо действий. Если кратко, то данные комментарии должны пояснять, зачем создан тот или иной класс и пакет и что делает тот или иной метод. Так же можно при необходимости описывать поля класса. Именно то, что оформлено в качестве JavaDoc мы и видим в подсказках наших IDE. Например: Если мы перейдем в этот метод, мы увидим, откуда взялся этот текст: То, как правильно оформлять JavaDoc опять же смотрим в Java Code Convention: Code Convention. Они чем-то похожи на блочные комментарии, но вместо одного астериска (не Астерикса)) используется два. Пример JavaDoc был приведен выше. С Java 23 у документирующих комментариев появился и второй синтаксис: три слэша /// в начале каждой строки, а разметка внутри пишется на Markdown вместо HTML-тегов (JEP 467). Описывать все возможности нет смысла, так как об этом уже написано в официальной документации Oracle. Поэтому все необходимое смотрим в официальной документации по JavaDoc, раздел "Standard Doclet Options". У Oracle есть даже отдельный tutorial на эту тему: How to Write Doc Comments for the Javadoc Tool. Подсказки в IDE это хорошо, но на самом деле они не просто так doc. На основе этих JavaDoc комментариев генерируется документация. Для этого есть специальная утилита javadoc. Как мы видим, в том Tutorial об этом и говорится. Описание того, как ей пользоваться, есть на официальном сайте Oracle для JavaDoc. Чтобы увидеть воочию, как это выглядит, можно создать в каталоге подкаталог с названием пакета, например: test. В нем создать простенький класс с комментариями. Например:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

После этого можно выполнить следующую команду из каталога, который содержит наш каталог с пакетом: javadoc -d ./doc test После этого мы увидим процесс генерации документации. И после можем открыть index.html, чтобы увидеть сгенерированный документ. Вы часто сможете увидеть, когда выставляют документацию по API. Например, Spring Framework API.

Заключение

Как мы видим, казалось бы, такая простая штука как комментарии на деле оказывается куда сложнее. В 2025 году комментарии стали еще более интегрированными в процесс разработки: от автоматической генерации с помощью AI до интеграции с системами мониторинга и compliance. Современные практики подчеркивают:

• Минимализм: комментируйте только то, что действительно нужно
• Контекст: объясняйте бизнес-логику и архитектурные решения
• Автоматизация: используйте AI и инструменты для поддержания качества
• Интеграция: связывайте комментарии с мониторингом, безопасностью и процессами команды

Если комментариям выделить некоторое время и за ними следить, ваш код будет лучше и вы как программист будете ценнее. А с современными инструментами 2025 года этот процесс стал намного проще и эффективнее.

Вопросы и ответы

Какие бывают комментарии в Java?

По синтаксису три вида: // до конца строки, /* ... */ на несколько строк и /** ... */ для документации. По назначению два: комментарии реализации, которые объясняют код, и документирующие, которые описывают публичный API.

Чем блочный комментарий отличается от JavaDoc?

Блочный /* ... */ существует только в исходнике и нужен человеку, который читает код. JavaDoc /** ... */ утилита javadoc превращает в HTML-документацию, а IDE показывает его в подсказке при наведении на метод.

Влияют ли комментарии на размер и скорость программы?

Нет. Компилятор отбрасывает комментарии на этапе компиляции, в .class-файл они не попадают. Ни на размер байт-кода, ни на скорость работы они не влияют.

Что означают TODO и FIXME в комментариях?

Это пометки для самого разработчика: TODO о том, что нужно доделать, FIXME о том, что нужно починить. IDE их распознает и собирает в отдельную панель, так что по проекту можно пройтись списком.

Как сгенерировать документацию из JavaDoc-комментариев?

Командой javadoc -d ./doc имя_пакета, запущенной из каталога, в котором лежит пакет. В указанной папке появится набор HTML-файлов, стартовый это index.html.

Сколько комментариев нужно писать?

Столько, чтобы объяснить, почему код написан именно так, а не что он делает. Понятные имена переменных и методов заменяют большинство поясняющих комментариев. Документирующие комментарии пишут для всего, что попадает в публичный API. Источник: Oracle: Code Conventions for the Java Programming Language, раздел Comments.

Читайте также

• Познаем IntelliJ IDEA
• IntelliJ IDEA: стиль и форматирование кода
• Модификаторы доступа: private, protected, default, public
• Для чего нужен класс PrintStream