java комментарии в коде

Комментарии

Обычно мы их используем, чтобы описать, как и почему работает код.

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

Плохие комментарии

Новички склонны использовать комментарии, чтобы объяснять, «что делает код». Например, так:

Но в хорошем коде количество «объясняющих» комментариев должно быть минимальным. Серьёзно, код должен быть таким, чтобы его можно было понять без комментариев.

Про это есть хорошее правило: «Если код настолько запутанный, что требует комментариев, то, может быть, его стоит переделать?»

Рецепт: выносите код в функции

Иногда выгодно заменить часть кода функцией, например, в таком случае:

Лучший вариант – использовать отдельную функцию isPrime :

Теперь код легче понять. Функция сама становится комментарием. Такой код называется самодокументированным.

Рецепт: создавайте функции

И если мы имеем такой длинный кусок кода:

То будет лучше отрефакторить его с использованием функций:

Здесь комментарии тоже не нужны: функции сами говорят, что делают (если вы понимаете английский язык). И ещё, структура кода лучше, когда он разделён на части. Понятно, что делает каждая функция, что она принимает и что возвращает.

В реальности мы не можем полностью избежать «объясняющих» комментариев. Существуют сложные алгоритмы. И есть хитрые уловки для оптимизации. Но в целом мы должны стараться писать простой и самодокументированный код.

Хорошие комментарии

Итак, обычно «объясняющие» комментарии – это плохо. Но тогда какой комментарий считается хорошим?

Сделайте высокоуровневый обзор компонентов, того, как они взаимодействуют, каков поток управления в различных ситуациях… Если вкратце – обзор кода с высоты птичьего полёта. Существует специальный язык UML для создания диаграмм, разъясняющих архитектуру кода. Его определённо стоит изучить.

Документируйте параметры и использование функций

Есть специальный синтаксис JSDoc для документирования функций: использование, параметры, возвращаемое значение.

Подобные комментарии позволяют нам понимать назначение функции и правильно её использовать без необходимости заглядывать в код.

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

Также существуют инструменты, например, JSDoc 3, которые умеют генерировать HTML-документацию из комментариев. Получить больше информации о JSDoc вы можете здесь: http://usejsdoc.org/.

Почему задача решена именно таким способом?

Важно то, что написано. Но то, что не написано, может быть даже более важным, чтобы понимать происходящее. Почему задача решена именно этим способом? Код не даёт ответа.

Если есть несколько способов решить задачу, то почему вы выбрали именно этот? Особенно если ваш способ – не самый очевидный.

Без подобных комментариев возможна следующая ситуация:

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

В коде есть какие-то тонкости? Где они используются?

Если в коде есть какие-то тонкости и неочевидные вещи, его определённо нужно комментировать.

Итого

Комментарии – важный признак хорошего разработчика, причём как их наличие, так и отсутствие.

Хорошие комментарии позволяют нам поддерживать код, дают возможность вернуться к нему после перерыва и эффективнее его использовать.

Комментируйте:

Избегайте комментариев:

Средства для генерации документации по коду, такие как JSDoc3, также используют комментарии: они их читают и генерируют HTML-документацию (или документацию в другом формате).

Источник

Java комментарии в коде

В Java вы можете использовать функции комментариев: вставлять документацию в исходный код. Комментарий с разделителями – это текст, который имеет смысл для человека, но не для компилятора. При компиляции исходного кода компилятор Java игнорирует все комментарии; он не генерирует байт-код для них. Java поддерживает однострочные, многострочные, и комментарии Javadoc. Давайте посмотрим на примеры для каждого из них.

Однострочный комментарий охватывает одну строку. Он начинается с // и продолжается до конца текущей строки. Компилятор игнорирует все символы из // до конца этой линии. Следующий пример представляет однострочный комментарий:

Однострочный комментарий полезен для определения короткого значимого описания данной строки кода.

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

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

Рассмотрим часто используемые теги Javadoc:

Генерируемая документация включает в себя индексный файл ( index.html ), который представляет собой стартовую страницу. Например, на рисунке ниже вы можете видеть стартовую страницу из документации Java SE 8 update 45 библиотеки API, сгенерированную Javadoc.

Данная статья представляет собой перевод с английского. Автор исходного текста Джефф Фризен, переводчик Юрий Пахолков. Если вам необходим качественный перевод с английского языка (включая специфические тексты по ИТ-тематике), то вы можете обратиться к нам: пишите на электронную почту up777up@yandex.ru с темой «перевод». Мы с удовольствием и за очень небольшую сумму в отечественной или иностранной валюте вам поможем.

статьи IT, java, комментарии, документация

Источник

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

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

Итак, рассмотрим простейшую программу на Java, которая содержит комментарии:

/**
* Данный комментарий описывает класс MyrusakovApp
* текст комментария может располагаться на нескольких строках
*/
class MyrusakovApp <

В Java существуют следующие виды комментариев:

/* простой текст. все что внутри игнорируется компилятором */

/**
* комментарий документации
*
* с помощью него создается комментарий документирования. Компилятор игнорирует все что находится внутри данного комментария
* Утилита javadoc использует этот тип комментариев для автогенерации документации. Необходимые параметры задаются с помощью
* специальных терминов
*
*/

// Просто однострочный комментарий, который распространяется до конца строки

Копирование материалов разрешается только с указанием автора (Михаил Русаков) и индексируемой прямой ссылкой на сайт (http://myrusakov.ru)!

Добавляйтесь ко мне в друзья ВКонтакте: http://vk.com/myrusakov.
Если Вы хотите дать оценку мне и моей работе, то напишите её в моей группе: http://vk.com/rusakovmy.

Если Вы не хотите пропустить новые материалы на сайте,
то Вы можете подписаться на обновления: Подписаться на обновления

Если у Вас остались какие-либо вопросы, либо у Вас есть желание высказаться по поводу этой статьи, то Вы можете оставить свой комментарий внизу страницы.

Порекомендуйте эту статью друзьям:

Если Вам понравился сайт, то разместите ссылку на него (у себя на сайте, на форуме, в контакте):

Комментарии ( 0 ):

Для добавления комментариев надо войти в систему.
Если Вы ещё не зарегистрированы на сайте, то сначала зарегистрируйтесь.

Copyright © 2010-2021 Русаков Михаил Юрьевич. Все права защищены.

Источник

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

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

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

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

Программист начального уровня использует в основном однострочные комментарии для описания функциональности кода. Это самые простые набранные комментарии.
Синтаксис:

// Java-программа для отображения однострочных комментариев

public static void main(String args[])

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

System.out.println( «Single line comment above» );

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

Описывать полный метод в коде или сложном фрагменте однострочных комментариев может быть утомительно, так как мы должны давать «//» в каждой строке. Таким образом, чтобы преодолеть это многострочные комментарии могут быть использованы.
Синтаксис:

// Java-программа для отображения многострочных комментариев

public static void main(String args[])

System.out.println( «Multi line comments below» );

/ * Строка комментария 1

Строка комментария 2

Строка комментария 3 * /

Мы также можем выполнить однострочные комментарии, используя приведенный выше синтаксис, как показано ниже:

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

Этот тип комментариев обычно используется при написании кода для пакета проекта / программного обеспечения, поскольку он помогает генерировать страницу документации для справки, которую можно использовать для получения информации о существующих методах, их параметрах и т. Д.
Например, http://docs.oracle.com/javase/7/docs/api/java/util/Scanner.html — это автоматически генерируемая страница документации, которая генерируется с использованием комментариев документации и инструмента javadoc для обработки комментариев.

Синтаксис:

Доступные теги для использования:

// Java-программа для иллюстрации часто используемых
// Теги комментариев

Найдите среднее из трех чисел!
* Программа FindAvg реализует приложение, которое
* просто вычисляет среднее из трех целых чисел и печатает
* вывод на экран.
*
* @author Pratik Agarwal
* @version 1.0
* @ since 2017-02-18
* /

public class FindAvg

* This method is used to find average of three integers.

* @param numA This is the first parameter to findAvg method

* @param numB This is the second parameter to findAvg method

* @param numC This is the second parameter to findAvg method

* @return int This returns average of numA, numB and numC.

public int findAvg( int numA, int numB, int numC)

return (numA + numB + numC)/ 3 ;

* This is the main method which makes use of findAvg method.

public static void main(String args[])

FindAvg obj = new FindAvg();

System.out.println( «Average of 10, 20 and 30 is :» + avg);

Выход:

Для приведенного выше кода документация может быть сгенерирована с помощью инструмента «javadoc»:
Javadoc можно использовать, выполнив следующую команду в терминале.

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

Источник

Документирование javadoc

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

Как правило, все существующие среды разработки IDE приложений Java предлагают решение по связыванию кода с документацией в процессе разработки с использованием javadoc. Для этого необходимо соответствующим образом написать комментарий к коду, т.е. документировать. Java комментарии необходимы как для комментирования программы, так и для составления или оформления документации.

Разработан специальный синтаксис для оформления документации в виде комментариев и инструмент для создания из комментариев документации. Этим инструментом является javadoc, который обрабатывая файл с исходным текстом программы, выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов, методов и полей. Таким образом, при минимальных усилиях создания комментариев к коду, можно получить хорошую документацию к программе.

javadoc — это генератор документации в HTML-формате из комментариев исходного кода Java и определяет стандарт для документирования классов Java. Для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения, javadoc также предоставляет API. В каждом случае комментарий должен находиться перед документируемым элементом.

При написании комментариев к кодам Java используют три типа комментариев :

С помощью утилиты javadoc, входящей в состав JDK, комментарий документации можно извлекать и помещать в НТМL файл. Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.

Дескрипторы javadoc, начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например , называются встроенными и могут применяться внутри описания.

Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.

javadoc дескрипторы : @author, @version, @since, @see, @param, @return

Форма документирования кода

В тело комментариев можно вставлять различные дескрипторы. Каждый дескриптор, начинающийся с символа ‘@’ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.

Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа «#» его метод или поле.

Среда разработки IDE, как правило, помогает программисту «подсветкой» встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.

Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы, для которого генерируется НТМL файл. Документация для каждого класса содержится в отдельном НТМL файле. Кроме этого, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL файлы.

Сценарии ant и javadoc

Для создания документации можно использовать ant.

Пример сценария (задания) ant для формирования документации к приложению MyProject :

Подробная информация формирования документации представлена на странице Javadoc/Javadoc2

Источник