Как использовать комментарии в коде Java

Комментарии Java - это примечания в файле кода Java, которые игнорируются компилятором и механизмом выполнения. Они используются для аннотирования кода, чтобы прояснить его дизайн и назначение. Вы можете добавить неограниченное количество комментариев к файлу Java, но при использовании комментариев следует соблюдать некоторые «рекомендации».

Как правило, комментарии кода являются комментариями «реализации», которые объясняют исходный кодтакие как описания классов, интерфейсов, методов и полей. Обычно это пара строк, написанных выше или рядом с кодом Java, чтобы прояснить, что он делает.

Другим типом комментариев Java является комментарий Javadoc. Комментарии Javadoc немного отличаются по синтаксису от комментариев реализации и используются программой javadoc.exe для создания документации HTML Java.

Зачем использовать комментарии Java?

Хорошей практикой является использование привычки вставлять комментарии Java в ваш исходный код, чтобы улучшить читаемость и ясность для себя и других программистов. Не всегда сразу понятно, что выполняет раздел кода Java. Несколько пояснительных строк могут значительно сократить время, необходимое для понимания кода.

instagram viewer

Они влияют на то, как работает программа?

Реализация комментариев в Java-код только для людей, чтобы читать. Java-компиляторы не заботятся о них и когда составление программыони просто пропускают их. Размер и эффективность вашей скомпилированной программы не будут зависеть от количества комментариев в вашем исходном коде.

Комментарии к реализации

Комментарии к реализации представлены в двух разных форматах:

Комментарии к строке: Для однострочного комментария введите «//» и следуйте за двумя косыми чертами с вашим комментарием. Например:
```
 // это однострочный комментарий
int guessNumber = (int) (Math.random () * 10); 
```
Когда компилятор сталкивается с двумя косыми чертами, он знает, что все, что справа от них, должно рассматриваться как комментарий. Это полезно при отладке фрагмента кода. Просто добавьте комментарий в строку кода, которую вы отлаживаете, и компилятор не увидит его:
- ```
 // это однострочный комментарий
// int guessNumber = (int) (Math.random () * 10); 
```
  Вы также можете использовать две косые черты, чтобы сделать комментарий в конце строки:
- ```
 // это однострочный комментарий
int guessNumber = (int) (Math.random () * 10); // конец строки комментария 
```
Блок комментариев: Чтобы начать комментарий к блоку, введите «/ *». Все, что находится между косой чертой и звездочкой, даже если оно находится на другой строке, рассматривается как комментарий до тех пор, пока символы "* /" не завершат комментарий. Например:
```
 /* это 
является 

блок
комментарий
*/
/ * так же это * /
```

Javadoc Комментарии

Используйте специальные комментарии Javadoc для документирования вашего Java API. Javadoc - это инструмент, включенный в JDK, который генерирует документацию HTML из комментариев в исходном коде.

Комментарий Javadoc в

.Джава

исходные файлы заключены в синтаксис начала и конца следующим образом:

/**

*/

. Каждый комментарий в них предваряется

Поместите эти комментарии непосредственно над методом, классом, конструктором или любым другим элементом Java, который вы хотите задокументировать. Например:

// myClass.java
/**
* Сделайте это краткое предложение, описывающее ваш класс.
* Вот еще одна строка.
*/
общественностиучебный класс мои занятия
{
...
}

Javadoc включает в себя различные теги, которые управляют созданием документации. Например,

@param

тег определяет параметры метода:

 / ** основной метод
* @param args String []
*/
общественностистатическийнедействительным main (строка [] args)
{
System.out.println («Привет, мир!»);
}

Многие другие теги доступны в Javadoc, и он также поддерживает теги HTML, чтобы помочь контролировать вывод. Смотрите документацию по Java для более подробной информации.

Советы по использованию комментариев

Не переусердствуйте с комментариями. Каждая строка вашей программы не нуждается в объяснении. Если ваша программа работает логически и ничего неожиданного не происходит, не нужно добавлять комментарий.
Сделайте отступ ваших комментариев. Если строка кода, которую вы комментируете, имеет отступ, убедитесь, что ваш комментарий соответствует отступу.
Оставляйте комментарии актуальными. Некоторые программисты отлично умеют изменять код, но по какой-то причине забывают обновлять комментарии. Если комментарий больше не применяется, измените или удалите его.

Не вкладывайте блоки комментариев. Следующее приведет к ошибке компилятора:

 /* это 
является
/ * Этот комментарий к блоку завершает первый комментарий * /

блок
комментарий
*/