Коментарі в 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