Внутри программы Java мы можем написать специальный текст, который будет проигнорирован компилятором Java — известный как комментарий. Комментарии позволяют нам исключить код из процесса компиляции(отключить его) или прояснить фрагмент кода для себя или других разработчиков.
Узнайте все о комментариях Java, типах комментариев Java, инструменте Javadoc, влиянии комментариев на производительность и передовых методах, которым следует следовать.
1. Зачем нам писать комментарии?
Комментарии, как следует из названия, это заметки, которые мы пишем между программами по разным причинам. Например, вы можете писать комментарии к –
- Напишите информацию или пояснение о переменной, методе, классе или любом операторе.
- Напишите текст, который будет доступен в документации Java.
- Скрыть код программы на определенное время и т. д.
Данный код является примером комментариев Java и того, как их использовать.
/*** Содержит метод приветствия пользователей по имени и местоположению.** @автор Локеш Гупта*/публичный класс Main {/*** Запускает приложение** @param args — Аргументы запуска приложения*/public static void main(String[] args) {getMessage("Локеш", "Индия");}/*** Возвращает приветственное сообщение для клиента по имени и местоположению клиента** @param name - Имя посетителя* @param region - Местоположение* @return — приветственное сообщение*/public static String getMessage(имя строки, область строки){Конструктор StringBuilder = новый StringBuilder();builder.append("Привет ");builder.append(имя);builder.append(", Добро пожаловать в ");builder.append(регион);builder.append(" !!");вернуть builder.toString();}}2. Типы комментариев Java
В Java существует 3 типа комментариев.
2.1. Однострочный комментарий
Используйте однострочные комментарии, когда комментарий можно написать только в одну строку. Эти комментарии пишутся поверх операторов Java, чтобы прояснить, что они делают.
//Initialize the counter variable to 0int counter = 0;
2.2 Многострочный комментарий
Используйте многострочные комментарии, когда вам нужно добавить информацию в исходный код, которая превышает одну строку. Многострочные комментарии используются в основном над блоками кода со сложной логикой, которые невозможно записать в одну строку.
/** This function returns a variable which shall be used as a counter for any loop.* Counter variable is of integer type and should not be reset during execution.*/public int getCounter() {//}2.3 Комментарий к документации Java
Комментарии к документации используются, когда вы хотите предоставить информацию, которую должен извлечь инструмент javadoc для создания HTML-документации для классов путем чтения исходного кода. Это информация, которую вы видите в редакторах(например, eclipse) при использовании функции автозаполнения. Эти комментарии располагаются над определениями классов, интерфейсов и методов.
- Комментарии к документации начинаются с /** и заканчиваются */. По соглашению каждая строка комментария документа начинается с *, как показано в следующем примере, но это необязательно. Любые начальные пробелы и * в каждой строке игнорируются.
- В комментарии документа строки, начинающиеся с @, интерпретируются как специальные инструкции для генератора документации, предоставляющие ему информацию об исходном коде.
- Внутри этих комментариев можно использовать аннотации Javadoc, например @param и @return.
/*** This function returns a variable which shall be used as a counter for any loop.* Counter variable is of integer type and should not be reset during execution.** @param seed - initial value of the counter* @return counter value*/public int getCounter(int seed) {//}Комментарии документа могут появляться над определениями классов, методов и переменных, но некоторые теги могут не применяться ко всем из них. Например, тег @exception может применяться только к методам.
| Ярлык | Описание | Применимо к |
|---|---|---|
| @видеть | Имя соответствующего класса | Класс, метод или переменная |
| @код | Содержание исходного кода | Класс, метод или переменная |
| @связь | Связанный URL-адрес | Класс, метод или переменная |
| @автор | Имя автора | Сорт |
| @версия | Номер версии | Сорт |
| @парам | Имя и описание параметра | Метод |
| @возвращаться | Тип возврата и описание | Метод |
| @исключение | Название и описание исключения | Метод |
| @устаревший | Объявляет элемент устаревшим | Класс, метод или переменная |
| @с | Версия API Notes на момент добавления элемента | Переменная |
Комментарии к документации являются неотъемлемой частью программирования и их нельзя игнорировать.
3. Сочетания клавиш для комментариев
В Eclipse IDE простой ввод «/** [Enter]» перед публичным методом или классом автоматически сгенерирует все необходимые атрибуты @param, @author и @return.
4. Утилита Javadoc
Утилита Javadoc поставляется вместе с дистрибутивами JDK. Она преобразует их в стандартизированные, красиво отформатированные, легко читаемые веб-страницы. Она генерирует документацию API из комментариев к документации.
4.1. Запустите javadoc из командной строки
Во-первых, убедитесь, что javadoc утилиты находится в вашем PATH. Если нет, то добавьте папку JDK/bin в переменную PATH.
Для генерации Java docs запустите утилиту с двумя аргументами. Первый — это расположение сгенерированных Java docs, а второй — исходные файлы Java. В нашем случае я выполнил эту команду из расположения, где находится Main.java.
$ javadoc -d C:/temp Main.java
Он сгенерировал эти HTML-файлы Java docs.
4.2 Запуск javadoc из Eclipse
Вы также можете сгенерировать документацию Java из Eclipse IDE. Выполните следующие простые шаги:
- В обозревателе пакетов щелкните правой кнопкой мыши нужный проект/пакет.
- Выберите Экспорт…/Javadoc и нажмите Далее.
- По умолчанию будет выбран весь исходный код. Проверьте и измените свой выбор.
- Вы можете выбрать «Private» для уровня видимости, который будет сгенерирован. Это сгенерирует все возможные Javadocs, даже для частных методов.
- Выберите «стандартный доклет», который является папкой назначения для вашей документации.
- Нажмите «Далее».
- Введите осмысленное название документа и нажмите «Готово».
Если вы правильно выполните все вышеперечисленные шаги, у вас будет сгенерирован файл документации Java, аналогичный тому, что мы видели в командной строке.
5. Влияние комментариев Java на производительность
Комментарии по реализации в коде Java предназначены только для чтения человеком. Комментарии Java — это операторы, которые не компилируются компилятором, поэтому они не включаются в скомпилированный байт-код(файл .class).
Вот почему комментарии Java также не влияют на производительность приложения.
6. Лучшие практики комментариев Java
Следуйте этим рекомендациям, чтобы иметь правильные комментарии в исходном коде вашего приложения.
- Не используйте ненужные комментарии в исходном коде. Если ваш код требует большего, чем обычное объяснение, то, возможно, выполните рефакторинг вашего кода.
- Для лучшей читабельности сохраняйте одинаковые отступы в комментариях.
- Комментарии предназначены для людей, поэтому объясняйте простым языком.
- Всегда добавляйте комментарии к документации в исходный код.