1.2.2. Коментарі

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

В Java коментарі бувають двох видів:

• рядкові

• блочні

Рядкові коментарі починаються з ASCII-символів // і тривають до кінця поточного рядка.

Як правило, вони використовуються для пояснення саме цього рядка, наприклад:

inty=1970; // рік народження

Блочні коментарі розміщуються міжASCII-символами /* і */, можуть займати довільну кількість рядків, наприклад:

/*

Цей цикл може починатися з нуля

із-за особливостей алгоритму

*/

for (inti=1; i<10; i++) {

. . .

}

Часто блочні коментарі оформляють так (кожний рядок починається з *):

/*

* Опис алгоритму роботи

* наступного циклу while

*/

while (x>0) {

. . .

}

Блочний коментар не обов’язково повинен розміщуватися на кількох рядках, він може навіть знаходитися в середині оператора:

floats = 2*Math.PI /*getRadius() */; // Коментар для налагодження

У цьому прикладі блочний коментар розбиває арифметичні операції. Вираз Math.PI представляє значення сталоїPI, визначене в класіMath. Виклик методуgetRadius() тепер за коментований і не буде викликаний, зміннаsзавжди набуватиме значення 2 PI. Завершує рядок рядковий коментар.

Коментарі не можуть знаходитися всередині символьних і рядкових літералів, ідентифікаторах (ці поняття детально розглядаються в подальшому).

Наступний приклад вказує на випадки неправильного застосування коментарів:

// В цьому прикладі текст /*…*/ стане частиною рядкаs

Strings = “text/*justtext*/”;

/*

*Наступний рядок стане причиною помилки при компіляції,

* оскільки коментар розбив ім’я методу getRadius ()

*/

circle.get/*comment*/Radius();

А такий код припустимий:

// Коментар може розділяти виклики функцій:

circle./*comment*/get.Radius();

// Коментар не може замінювати пробіли:

int /*comment*/x=1;

В останньому рядку між назвою типу даних int і назвою змінної xобов’язково повинен бути пробіл або, як і в даному прикладі, коментар.

Коментарі не можуть бути вкладеними. Символи /*, */, // не мають ніякого особливого значення всередині вже відкритих коментарів, як рядкових, так і блочних. Отже, в наступному прикладі

/* початок коментаря */ // */** завершення тут: */

описано рівно один блочний коментар. А в наступному прикладі (рядки коду пронумеровані для зручності)

1./*

2. comment

3. /*

4. more comments

5. */

6. finish

7. */

компілятор видасть помилку. Блочний коментар почався в рядку 1 з комбінації символів /*. Друга комбінація /*, яка відкриває коментар на рядку 3, буде проігнорована, оскільки знаходиться вже всередині коментаря. Символи */ в рядку 5 завершать його, а рядок 7 породить помилку – спроба закрити коментар, який не був розпочатий.

Будь-які коментарі повністю вилучаються з програми під час компіляції, тому їх можна використовувати необмежено, не боячись, що вони впливатимуть на бінарний код. Основне їх застосування – зробити програму простою для розуміння, зокрема й інших розробників, яким прийдеться з будь-якої причини розбиратися в ній.

Коментарі часто використовують для тимчасового виключення частин коду, наприклад:

int x = 2;

int y = 2;

/*

if (x > 0)

y = y + x*2;

else

y = -y – x*4;

*/

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

У цьому прикладі за коментовано вираз if-else і оператор +2*x.

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

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

Коментар розробника записується так само, як і блочний. Єдина відмінність в початковій комбінації символів – для документації коментар треба починати з /**. Наприклад:

/**

* Обчислення модуля цілого числа.

* Цей метод повертає

* абсолютне значення аргументу x.

*/

intgetAbs (intx) {

if (x>0)

renurnx;

else

return –x;

}

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

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

Символ * на початку кожного рядка і пробіли та знаки табуляції, які йому передують, ігноруються. Їх можна взагалі не використовувати, але вони зручні, коли важливе форматування, наприклад, в прикладах коду.

/**

* Перше речення – короткий опис методу.

* <p>

* Так оформляється приклад коду:

* <blockquote>

* <pre>

* if (condition==true) {

* x = getWidht ();

* y = x.getHeight ();

*}

* </pre></blockquote>

* А так описується HTML-список:

* <u1>

* <li>Можна використовувати похилий шрифт<i> курсив</i>,

*<li>або жирний<b>жирний</b>.

* </u1>

*/

public void calculate (int x, int y) {

. . .

}

З цього коментаря генерується HTML-код, який виглядатиме приблизно так:

Перше речення – короткий опис методу.

Так оформляється приклад коду:

if (condition==true){

x = getWidht ();

y = x.getHeight ();

}

А так описується HTML-список:

. Можна використовувати похилий шрифт курсив,

. або жирний жирний.

Крім цього, Javadoc підтримує спеціальні теги. Вони починаються символом @. Детальний опис цих тегів модна знайти в документації. Наприклад, можна використовувати тег @see, щоб можна було посилатися на другий клас, поле або метод, або навіть на інший інтернет-сайт

/**

* Короткий опис.

*

*Розгорнутий коментар.

*

* @seejava.land.String

* @seejava.land.Math#PI

* @see<ahref=”java.sun.com”>OfficialJavasite</a>

*/

Перше посилання вказує на клас String (java.land – назва бібліотеки, в якій знаходиться цей клас), друге – на поле PI класуMath(символ # розділяє назву класу і його полів або методів), третя посилається на офіційний сайтJava.

Коментарі розробника можуть бути записані перед оголошенням класів, інтерфейсів, полів, методів і конструкторів. Якщо записати коментар /** … */ в другій частині коду, то помилки не буде, але він не попаде в документацію, яка генерується javadoc. Крім цього, можна описати й пакет (так називаються бібліотеки або модулі вJava). Для цього необхідно створити спеціальний файлpackage.html, зберегти в ньому коментар, і розмістити його в директорію пакету.HTML-текст, який знаходиться між тегами<body> і</body>, буде розміщений в документацію, а перше речення буде використане для короткої характеристики цього пакета.

Всі класи стандартних бібліотек Java постачаються як початковий текст, і можна побачити, як вони добре коментовані. Стандартна документація цих класів генерована утилітоюjavadoc. Для будь-якої програми можна легко підготувати подібний опис, необхідні тільки грамотні і акуратні коментарі в початковому коді. Крім цього,Java надає можливість генерувати за допомогоюjavadoc документацію з нестандартним зовнішнім виглядом.