Java-комментарии

Предыдущий урок –› Приведение типов Java

Следующий урок –› Операторы Java

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

Код также читается людьми, и мы хотим, чтобы наши намерения были понятны людям точно так же, как мы хотим, чтобы наши инструкции были понятны компьютеру.

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

Типы комментариев в Java

В Java есть три типа комментариев:

однострочный комментарий
многострочный комментарий
комментарии к документации

Однострочные комментарии

Однострочные комментарии начинаются с двух косых черт (//).

Любой текст между // и концом строки игнорируется Java (не будет выполняться).

В этом примере используется однострочный комментарий перед строкой кода:

// This is a comment
System.out.println("Hello World");

В этом примере используется однострочный комментарий в конце строки кода:

System.out.println("Hello World"); // This is a comment

Многострочные комментарии

Когда мы хотим написать комментарии в несколько строк, мы можем использовать многострочные комментарии.

Многострочные комментарии начинаются с /* и заканчиваются на */.

Любой текст между /* и */ будет игнорироваться Java.

В этом примере для пояснения кода используется многострочный комментарий (блок комментариев):

/* The code below will print the words Hello World
to the screen, and it is amazing */
System.out.println("Hello World");

Комментарии к документации

Другим типом комментария является комментарий Javadoc, который представлен /** и */. Комментарии Javadoc используются для создания документации для API (интерфейсов прикладного программирования). При написании комментариев Javadoc помните, что в конечном итоге они будут использоваться в документации, которую могут читать ваши пользователи, поэтому будьте особенно внимательны при написании этих комментариев.

Комментарии Javadoc обычно пишутся перед объявлением полей, методов и классов (которые мы рассмотрим позже в этом курсе):

/**
* The following class accomplishes the following task...
*/

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

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

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

Примечание. В большинстве случаев всегда используйте комментарии, чтобы объяснить «почему», а не «как», и все готово.