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

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

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

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

Содержание

Зачем нужны комментарии Java?
Влияют ли они на работу программы?
Комментарии к реализации
Комментарии Javadoc
Советы по использованию комментариев

Зачем нужны комментарии Java?

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

Влияют ли они на работу программы?

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

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

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

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

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

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

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

.  Исходные файлы java

заключены в синтаксис начала и конца, например:

/**

*/

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

* 
 . Поместите эти комментарии непосредственно над методом, классом, конструктором или любым другим элементом Java, который вы хотите задокументировать.  Например: 
  
 //myClass.java 
/** 
 * Сделайте это итоговое предложение, описывающее ваш класс. 
 * Вот еще одна строка. 
 */
  public   class  myClass 
 {
 ... 
} 
 
 
 Документация Javadoc включает различные теги, которые контролируют создание документации.  Например, 
@param 
 /** основной метод 
 * @param args String [] 
 */
  public   static   void  main (String [] args) 
 {
 System.out.println ("Hello World!"); 
} 
 
 
 Многие другие теги доступны в Javadoc, и он также поддерживает теги HTML, помогающие контролировать вывод.  См. Дополнительную информацию в документации по Java. 
 
 Советы по использованию комментариев 

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