Программирование на Java

/ y = yy;// + 2*x;

В этом примере закомментировано выражение if-else и оператор сложения +2*x.

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

Кроме этого, существует особый вид блочного комментария – комментарий разработчика. Он применяется для автоматического создания документации кода. В стандартную поставку JDK, начиная с версии 1.0, входит специальная утилита javadoc. На вход ей подается исходный код классов, а на выходе получается удобная документация в HTML-формате, которая описывает все классы, все их поля и методы. При этом активно используются гиперссылки, что существенно упрощает изучение программы (например, читая описание метода, можно с помощью одного нажатия мыши перейти на описание типов, используемых в качестве аргументов или возвращаемого значения). Однако понятно, что одного названия метода и перечисления его аргументов недостаточно для понимания его работы. Необходимы дополнительные пояснения от разработчика.

Комментарий разработчика записывается так же, как и блочный. Единственное различие в начальной комбинации символов – для документации комментарий необходимо начинать с /**. Например:

/** Вычисление модуля целого числа. Этот метод возвращает абсолютное значение аргумента x. / int getAbs(int x) { if (x>=0) return x; else return -x; }

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

Поскольку в результате создается HTML-документация, то и комментарий необходимо писать по правилам HTML. Допускается применение тегов, таких как <b> и <p>. Однако теги заголовков с <h1> по <h6> и <hr> использовать нельзя, так как они активно применяются javadoc для создания структуры документации.

Символ в начале каждой строки и предшествующие ему пробелы и знаки табуляции игнорируются. Их можно не использовать вообще, но они удобны, когда необходимо форматирование, скажем, в примерах кода.

/* Первое предложение - краткое описание метода. <p> Так оформляется пример кода: <blockquote> <pre> if (condition==true) { x = getWidth(); y = x.getHeight(); } </pre></blockquote> А так описывается HTML-список: <ul> <li>Можно использовать наклонный шрифт <i>курсив</i>, <li>или жирный <b>жирный</b>. </ul> / public void calculate (int x, int y) { ... }

Из этого комментария будет сгенерирован HTML-код, выглядящий примерно так:

Первое предложение – краткое описание метода. Так оформляется пример кода: if (condition==true) { x = getWidth(); y = x.getHeight(); } А так описывается HTML-список: Можно использовать наклонный шрифт курсив, или жирный жирный.

Наконец, javadoc поддерживает специальные теги. Они начинаются с символа @. Подробное описание этих тегов можно найти в документации. Например, можно использовать тег @see, чтобы сослаться на другой класс, поле или метод, или даже на другой Internet-сайт.

/** Краткое описание. Развернутый комментарий. @see java.lang.String @see java.lang.Math#PI @see <a href='java.sun.com'>Official Java site</a> /

Первая ссылка указывает на класс String