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

Вступление

Комментарии — казалось бы, что может быть проще, и чего тут целую статью писать. Но тут не всё так просто. Как говорил мой начальник, код писать может каждый, а вот хороший комментарий написать сложно. Большинство курсов по изучению языка начинаются с традиционного 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 они собираются на отдельной вкладке, где их можно посмотреть: И небольшой puzzler с комментарием: Строка «http://google.com» является корректной строчкой внутри метода, т.к. http здесь — это на самом деле метка, а дальше — комментарий. Зачастую многие комментарии могут стать из комментариев кода комментарием для документирования, о которых поговорим далее.

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

Комментарии для документации описывают общедоступный API. API — это програмный интерфейс приложения, то есть те классы и методы, которые доступны другим разработчикам для выполнения каких-либо действий. Если кратко, то данные комментарии должны пояснять, зачем создан тот или иной класс и пакет и что делает тот или иной метод. Так же можно при необходимости описывать поля класса. Именно то, что оформлено в качестве JavaDoc мы и видим в подсказках наших IDE. Например: Если мы перейдём в этот метод, мы увидим, откуда взялся этот текст: То, как правильно оформлять 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 После этого мы увидим процесс генерации документации. И после можем открыть index.html, чтобы увидеть сгенерированный документ. Вы часто сможете увидеть, когда выставляют документацию по API. Например, Spring Framework API.

Заключение

Как мы видим, казалось бы, такая простая штука как комментарии на деле оказывается куда сложнее. Поэтому, если комментариям выделить некоторое время и за ними следить, ваш код будет лучше и вы как программист будете ценнее. #Viacheslav