JavaRush /Java блог /Random /Комментарии в Java: не всё так просто
Viacheslav
3 уровень

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

Статья из группы Random

Вступление

Комментарии — казалось бы, что может быть проще, и чего тут целую статью писать. Но тут не всё так просто. Как говорил мой начальник, код писать может каждый, а вот хороший комментарий написать сложно. Комментарии в Java: не всё так просто - 1Большинство курсов по изучению языка начинаются с традиционного 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 подсказки. Например, при помощи строчных комментариев «//@formatter:on» и «//@formatter:off» в IDE Eclipse можно отключить форматирование для участков кода. Использовать комментарии нужно размеренно и только там, где это необходимо. Например, можно прочитать статью на эту тему: «Не пишите комментарии к коду!». Есть отличная книга "Чистый код: создание, анализ и рефакторинг", которую написал Роберт Мартин. В ней есть отдельная глава «Комментарии». В качестве эпиграфа к этой главе — не менее отличная цитата: «Не комментируйте плохой код — перепишите его» от Брайана У. Кернигана и П. Дж. Плауэра. С данной главой можно ознакомиться на Google Books. Общий смысл можно выразить в одной его цитате:
Каждый раз, когда вы пишите комментарий, поморщитесь и ощутите свою неудачу»
Понятно, что нет абсолютной истины, и иногда комментарии необходимы. Но всегда есть варианты, и с излишними комментариями нужно бороться. В этой же главе упоминаются необычные комментарии, TODO:

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

Смысл в них в том, что они могут особым образом обрабатываться в IDE. Например, в IDEA они собираются на отдельной вкладке, где их можно посмотреть:
Комментарии в Java: не всё так просто - 2
И небольшой puzzler с комментарием: Строка «http://google.com» является корректной строчкой внутри метода, т.к. http здесь — это на самом деле метка, а дальше — комментарий. Зачастую многие комментарии могут стать из комментариев кода комментарием для документирования, о которых поговорим далее.

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

Комментарии для документации описывают общедоступный API. API — это програмный интерфейс приложения, то есть те классы и методы, которые доступны другим разработчикам для выполнения каких-либо действий. Если кратко, то данные комментарии должны пояснять, зачем создан тот или иной класс и пакет и что делает тот или иной метод. Так же можно при необходимости описывать поля класса. Именно то, что оформлено в качестве JavaDoc мы и видим в подсказках наших IDE. Например:
Комментарии в Java: не всё так просто - 3
Если мы перейдём в этот метод, мы увидим, откуда взялся этот текст:
Комментарии в Java: не всё так просто - 4
То, как правильно оформлять JavaDoc опять же смотрим в Java Code Convention: Code Convention. Они чем-то похожи на блочные комментарии, но вместо одного астериска (не Астерикса)) используется два. Пример JavaDoc был приведён выше. Описывать все возможности нет смысла, так как об этом уже написано в официальной документации Oracle. Поэтому всё необходимое смотрим в официальной документации по JavaDoc, раздел "Tag Descriptions". У 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 ./test test После этого мы увидим процесс генерации документации.
Комментарии в Java: не всё так просто - 5
И после можем открыть index.html, чтобы увидеть сгенерированный документ. Вы часто сможете увидеть, когда выставляют документацию по API. Например, Spring Framework API.

Заключение

Как мы видим, казалось бы, такая простая штука как комментарии на деле оказывается куда сложнее. Поэтому, если комментариям выделить некоторое время и за ними следить, ваш код будет лучше и вы как программист будете ценнее. #Viacheslav
Комментарии (21)
ЧТОБЫ ПОСМОТРЕТЬ ВСЕ КОММЕНТАРИИ ИЛИ ОСТАВИТЬ КОММЕНТАРИЙ,
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ
Anonymous #3420782 Уровень 1
27 февраля 2024
Очень познавательно!
Spider101Venom Уровень 2
4 января 2024
Кароче, сдох пока читал: длинно, странно, бесполезно, но за старания 5.
Alexander Smith Уровень 2
2 января 2024
Класс! Обязательно в "Закладки"!
Anonymous #3328548 Уровень 26
28 сентября 2023
Пожалуй, для начала рановато)
Pigeon_D04 Уровень 3
26 мая 2023
Что-то на умном 😅
hidden #3165671 Уровень 3
24 сентября 2022
Вернусь сюда позже 🤪
Anonymous #3156529 Уровень 1
18 сентября 2022
У нас настолько внимательные люди, что даже если написать: ... большую статью о правилах написания комментариев, которая может быть сложноватой для новичков, но будет интересна тем, у кого уже есть опыт программирования. Все равно найдутся такие, кто напишет, что сложновато для новичков. 🤷‍♂️
Taimik Уровень 3
30 августа 2022
Не совсем понятно. Точнее понятно какими-то фрагментами.
Anonymous #3119682 Уровень 1
14 июля 2022
Из данной статьи необходимо понять то, что комментарии могут гораздо больше. А если хочется узнать подробнее, то нужно читать документацию от Oracle. Лично я нахожу статью интересной, узнал много нового о возможностях комментариев и сделал для себя вывод, что если понадобится что-то описать, найду в инете как и опишу, а без этой статьи даже не узнал бы, что это возможно.
Serine Уровень 3
22 декабря 2021
🤦‍♀️