Комментарии в языке Java

Комментарии в языке Java — как и в большинстве других языков программирования, символы, которые игнорируются при выполнении программы. Таким образом, в программу можно добавлять столько комментариев, сколько потребуется, не опасаясь увеличить ее объем. Комментарии используются для описания тонкостей работы конкретного блока кода, метода или класса. Также можно использовать их, если хочется оставить сообщения для программистов, которые в будущем будут работать с этим кодом. Ну или же для собственных заметок.

Способы выделения комментариев

В языке Java есть два способа выделения комментариев в тексте.

Комментарий реализации (комментарий кода)

1. Комментирование строки

   Это самый часто используемый тип комментариев. Чтобы написать такой комментарий, нужно использовать две косые черты //. При этом комментарий начинается сразу за символами // и продолжается до конца строки.

   System.out.println("Hello, Java world!");
   // наш комментарий

2. Комментирование блока текста

   Если нужны более длинные комментарии, можно каждую строку начинать символами. Хотя более удобно ограничивать блоки комментариев разделителями /* и */.

   /*
    Пример простой программы на Java
   */
   
   public class SampleProgram
   {
    public static void main (String [] args)
    {
    System.out.println("Hello, Java world!");
    }
   }

   Не следует забывать, что комментарии, выделяемые символами /* и */ в языке Java не могут быть вложенными. Это значит, что фрагмент кода нельзя отключить, просто окружив его /* и */, поскольку отключаемый код сам может содержать разделители /* и */.

Документирующий комментарий

Для документирования методов, переменных или классов используется особый способ выделения текста. Делается это с помощью /** и */. При этом каждая строка комментируемого текста начинается с *.Если документируется метод, принято описывать его аргументы и возвращаемое значение.

/**
* Метод возвращает максимальное значение
* из трех переданных аргументов
* @param a - первый параметр
* @param b - второй параметр
* @param c - третий параметр
* @return - максимальный из параметров
*/
public int max(int a, int b, int c) {
   return Math.max(Math.max(a, b), c);
}

Что еще почитать? Например, этот материал: Комментарии в Java: не всё так просто. Или лекцию из квеста Java Syntax Pro о комментариях.