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

Содержание

Комментарии в коде — полезные, бессмысленные, вредные? / Хабр

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

Поэтому я выскажу несколько немного провокационных утверждений, затем попробую подкрепить их примерами. Посмотрим что получится. Написанное относится как к (Java) Doc, так и к обычным комментариям в коде.

Итак:

1. Комментарий может быть полезным, бессмысленным или вредным.
2. Если комментарий не несет явно видимой пользы, то он скорее всего вреден.
3. Комментарии бесполезны / вредны чаще, чем кажется. Отсутствие комментария лучше, чем бесполезный комментарий.
4. Перед тем, как написать комментарий — подумайте дважды, а может не стоит? 🙂
(5. После того, как вы решили, что комментарий все-таки не нужен, посмотрите трижды — а код точно кристалльно понятен?:))

Про полезные комментарии все ясно. Когда:
— достаточно прочитать 6 строк комментария вместо 80 строк кода метода с бизнес-логикой
— в комментарии дается ссылка на реализуемый малоизвестный алгоритм или структуру данных (например — «для поиска подстроки используется алгоритм Ахо — Корасик», ссылка на википедию или спец. сайт)
— комментарий поясняет, почему автор использует не тот подход, который читающий код скорее всего ожидает тут увидеть (например, написанный руками SQL запрос вместо работы через ORM фреймворк, или почему для поиска в XML используется regexp, а не XPath)
— в комментарии дан короткий ясный пример использования (особенно, если это какой-нибудь custom Ant task или что-то подобное),

то это почти наверняка полезный, а подчас необходимый комментарий.

А теперь посмотрим на некоторый другой часто встречающийся пример.
Такой комментарий обычно создается IDE по умолчанию при генерации геттеров-сеттеров для поля объекта (в свой очередь, если бы в Java были свойства, и необходимые синтетические методы генерились компилятором прозрачно для программиста, этой проблемы бы тоже не было :)).

/**
* return the enterpriseName
*/
public String getEnterpriseName() {
return enterpriseName;
}

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

Тут, конечно, есть тонкий момент. Если код с подобными комментариями — это часть public API какой нибудь generic библиотеки, и никто из пользующихся ей программистов почти никогда не смотрит ее исходники, а смотрит Javadoc — тогда это еще нормально. Но если этот код находится в каком нибудь модуле, разработываемом нами, и исходники этого класса смотрят чаще, чем документацию к нему (что почти всегда верно) — тогда это ИМХО, тот случай, когда правило «любой элемент API должен иметь комментарий» должно применяться с большой осторожностью.

Рассмотренный пример часто дополнительно ухудшается тем, что в комментарий запихиваются теги param, return, которые часто полезной информации не несут, а вот место съедают. Например:

/**
*
* Some description.
* param paramName1 paramName1
* param paramName2 paramName2
* param paramName3 paramName3
* return the name of user
*/
public String getUserName(String paramName1, int paramName2, int paramName2) {
/* какой то простой прямолинейный код*/
}

(Забавно, что часто в коде есть такие бессмысленные комментарии, а в реально сложных частях комментариев мало :))

И напоследок еще пример.

// Временный хак, т.к. возможность сделать нормально сейчас не поддерживается,
// а сделать надо срочно. По совету [senior developer name], хакнул так.
// 21/04/2004, [developer name].

В некоторых примерах я частично утрирую, но общая идея от этого не меняется.

Updated:
По просьбам в комментах, даю ссылку на пару книг, которые полезно прочитать любому программисту, чтобы не писать таких комментариев (и не делать многих других ошибок)

Стив МакКоннелл. Совершенный код. www.ozon.ru/context/detail/id/5508646
Мартин Фаулер. Рефакторинг. Улучшение существующего кода. www.ozon.ru/context/detail/id/4952415

Как комментировать в Java?

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

Важность комментариев

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

Делает код легко читаемым.
Легкое обслуживание кода и обнаружение ошибок.
Предоставьте сведения об определенном методе, классе, переменной или операторе.
Функции, написанные для использования другими, становятся более понятными.

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

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

В Java есть три подхода к комментированию, как показано ниже.

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

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

Вот синтаксис однострочного комментария Java:

// Это однострочный комментарий

Пример

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

Если вы хотите прокомментировать несколько строк исходного кода Java, используйте многострочный комментарий. Он начинается с /* и заканчивается */. Текст, написанный между ними, не будет выполняться компилятором Java.

Синтаксис

/* Это многострочный комментарий */

Пример

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

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

Вот синтаксис комментария типа документации в Java.

/**
*
*Для отображения параметров мы используем различные теги
*или метод или заголовок
*Или мы можем использовать теги HTML
*
*/

Пример

Приведенная ниже таблица охватывает несколько типов тегов javadoc.

Название тэга	Синтаксис	Описание
@автор	@автор имя-текст	Он используется для записи имени автора определенного класса.
@версия	@version версия-текст	Он используется для упоминания текста версии.
@параметр	@param-имя параметра описание	Используется для добавления имени и описания параметра.
@возвращение	@вернуть описание	Он используется для простого поиска возвращаемых значений путем создания раздела «Возвраты».
@устарело	@deprecated устаревший текст	Он используется для указания устаревшего класса или метода или поля и создает предупреждение каждый раз, когда он используется кем-то.
@поскольку	@с момента выпуска	Он используется для указания версии метода или класса и т. д. путем добавления раздела «с тех пор».
@бросает	@выдает описание имени класса	Он используется для создания исключения.
@исключение	Описание имени класса @exception	Он используется аналогично тегу @throw.
@видеть	@см. ссылку	Он используется для добавления ссылки на метод или класс путем создания ссылки в разделе «см. также».
@сериал	@serial описание поля \| включить \| исключать	Он используется для добавления соответствующей информации о сериализованных полях.
@serialField	@serial имя-поля тип-поля описание-поля	Он используется для документирования компонента ObjectStreamField.
@serialData	@serialData описание данных	Он используется для документирования данных, записанных такими методами, как writeObject() или writeExternal().
{@docRoot}	{@docRoot}	Он используется для отображения пути к корневому каталогу.
@код	{@кодовый текст}	Используется для отображения текста кодовыми шрифтами.
{@ценность}	{@значение пакета.класс#поле}	Он используется для отображения значения константы, когда комментарий документа записывается в статическое поле.
{@inheritDoc}	—–	Он используется для наследования комментария от наследуемого класса.
{@ссылка на сайт}	{@link package.class#member label}	Он включает в себя ссылку, которая фокусирует документацию для конкретного пакета, класса или имени члена класса, на который ссылаются.
{@linkplain}	{@linkplain package.class#member label}	Аналогичен ссылке, с той лишь разницей, что метка ссылки отображается в виде простого текста, а не кода.

Вывод

В Java есть три вида комментариев. Первый представляет собой однострочный комментарий, начинающийся с двух косых черт «//», второй — многострочный комментарий, начинающийся с /* и заканчивается на */, а последний — это комментарий к документации, который используется для создания API документации для больших программ Java и Приложения. Все эти типы комментариев объясняются в этом руководстве вместе с тегами javadoc, которые используются в комментариях к документации.