Комментарии java: Комментарии | Java | CodeBasics

Комментарии. Javadoc . Объектно-ориентированное программирование на Java. Платформа Java SE

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

Программы могут содержать сотни тысяч строк кода.

И очень сложно отслеживать все возможности.

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

Для этого можно использовать комментарии.

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

Еще одна возможность – это изготовить сопроводительную документацию к программе.

Javadoc – это инструмент, который является генератором документации на основе специальных комментариев.

Если вы используете эти специальные комментарии, вы можете автоматически создать хорошую документацию.

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

Здесь мы видим один из возможных способов написания комментария.

Комментарий начинается с косой черты и звездочки и заканчивается звездочкой и косой чертой.

Комментарий может включать в себя несколько строк.

Здесь у нас есть еще один комментарий.

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

Но на разных строках есть еще несколько звездочек.

И это указание для специальной программы под названием Javadoc.

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

Специальные команды, такие как @param и @return, имеют смысл, который Javadoc понимает при подготовке итоговой документации.

Операционная система компьютера, веб-браузер, приложения мобильного телефона, все они – состоят из очень сложных частей программного обеспечения.

Например, смартфон с операционной системой Android имеет более 12 миллионов строк кода.

Из них более 2 миллионов написано на языке Java.

Представьте себе, что вы кодируете все эти строки самостоятельно.

Вам понадобится много времени.

Как программистам, нам нужно работать с другими программистами для достижения цели.

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

Также и другие программисты вполне вероятно будут работать с нашим кодом.

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

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

Эти примечания в программе – это то, что мы называем комментариями.

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

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

Как и во всем, что есть в жизни, существуют разные подходы в том, как мы можем писать эти комментарии.

Комментарии полезны для разных целей.

Например, описание кода, то есть резюмирование целей сегмента кода.

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

Комментирование сегмента кода, который не работает должным образом.

Или автоматическое создание документации.

В Java существуют разные способы написания комментариев.

Сначала, мы сосредоточимся на тех типах комментариев, которые направленны на предоставление сведений о вашем коде вам и другим программистам.

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

И комментарий будет идти до конца строки.

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

И мы закончим комментарий звездочкой, а затем косой чертой.

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

Будьте осторожны и избегайте вложения друг в друга этих типов комментариев.

Существуют рекомендации по написанию кода на языке Java.

Советуют использовать комментарии с несколькими строками только при комментировании блока кода.

И использовать однострочные комментарии для всего остального.

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

Для этого нет однозначного ответа.

Убедитесь, что ваши комментарии соответствуют вашему коду.

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

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

То есть, дает хорошие комментарии.

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

Существует программа под названием Javadoc, которая генерирует документацию из кода Java в HTML-файлы, чтобы мы могли легко их прочитать в нашем браузере.

Документация в Java-коде должна начинаться с косой черты, а затем идут две звездочки, и заканчивается одной звездочкой, а затем косой чертой.

Javadoc просматривает вашу программу, ища строки, начинающиеся с косой черты и двух звездочек, и создает HTML-документацию.

Но почему мы должны использовать этот комментарий?

Вместо поиска комментариев в миллионах строк кода, вы можете открыть веб-страницу и найти всю важную информацию о программе.

Когда мы говорим в Java об автоматической генерации документации, мы используем термин Javadoc.

Какую информацию мы должны включить в Javadoc?

На сайте Oracle вы можете найти руководство по эффективной практике написания комментариев для инструмента Javadoc.

Мы попытаемся обобщить наиболее важные из них, используя пример.

Мы начнем с определения Javadoc-комментария.

Комментарий Javadoc написан в формате HTML и должен предшествовать коду.

Он состоит из двух частей: описания и блока тегов.

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

Давайте посмотрим на метод, который здесь указан, и вид информации, которая должна быть предоставлена для него в Javadoc.

Вы должны начать свой комментарий Javadoc с краткого и полного описания того, что делает этот метод.

Если в вашем Javadoc-комментарии есть несколько абзацев, разделите их тэгом p.

Затем вставьте пустую строку комментария, между описанием и блоком тегов.

Обратите внимание, что каждый комментарий Javadoc имеет только одно описание.

И как только инструмент Javadoc найдет пустую строку, он решит, что описание закончено.

Затем вы используете теги для добавления информации о вашем методе.

Наконец, вы должны поместить в конце строку со звездочкой и косой чертой, чтобы отметить конец комментария Javadoc.

Какая информация должна быть включена в блок тегов?

Для описания метода нам понадобятся, в основном, два типа тегов – @param и @return.

@param описывает аргумент метода.

И его необходимо указать для всех аргументов метода.

За тегом всегда следует имя аргумента.

Это имя всегда указывается в нижнем регистре.

Затем идет описание аргумента.

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

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

Чтобы разделить имя, описание и тип данных аргумента, вы можете добавить один или несколько пробелов.

Теги @param должны быть перечислены в порядке объявления аргумента.

Что касается описания, если это фраза без глагола, начните его с маленькой буквы.

Если это предложение с глаголом, начните его с заглавной буквы.

Таким образом, Javadoc – это полезный инструмент, который позволяет программистам автоматически генерировать HTML-страницы с документацией из их кода.

Данный текст является ознакомительным фрагментом.

комментарии — Java conventions, комментирование

Задать вопрос

Вопрос задан 2 года 3 месяца назад

Изменён 2 года 3 месяца назад

Просмотрен 362 раза

Мне непонятен этот пункт:

Block comments can start with /*-, which is recognized by indent(1)

as the beginning of a block comment that should not reformatted. Example:

/*
 * Here is a block comment with some very special
 * formatting that I want indent(1) to ignore.
 *
 * one
 *    two
 *       three
 */

Note: If you don’t use indent(1), you don’t have to use /*- in your code or make any other concessions to the possibility that someone else might run indent(1) on your code.

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

Как правильно должен быть оформлен комментарий, который потом не будет изменен автоматически, если он не по правилам?

• java
• комментарии
• javadoc

6

Комментарии бывают двух разных типов:

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

и

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

Разницы между ними нет (кроме того, что первый — однострочный, а второй — многострочный), а обязательное оформление я вам показал.

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

5

См. Code Conventions for the Java Programming Language: 5. Comments:

В Java-программах могут быть два вида комментариев: комментарии к реализации и комментарии к документации. Комментарии к реализации — это комментарии, унаследованные из C++, которые разделяются символами /*...*/ и //. Комментарии к документации (также известные как javadoc) предназначены только для Java и разделяются символами /**...*/. Эти комментарии можно извлечь в HTML-файлы с помощью специального инструмента.

Например, откроем исходный код класса java.lang.String. Сверху идёт многострочный комментарий /*...*/ об авторских правах, далее перед самим классом и перед его методами идут javadoc, также по коду встречаются однострочные комментарии //.
В онлайн докумнтацию HTML попадает только javadoc, другие комментарии не попадают.

При переформатировании кода, однострочные и многострочные комментарии изменяться не будут — изменится только javadoc, внутри можно использовать разметку HTML.

Зарегистрируйтесь или войдите

Регистрация через Google

Регистрация через Facebook

Регистрация через почту

Отправить без регистрации

Почта

Необходима, но никому не показывается

Отправить без регистрации

Почта

Необходима, но никому не показывается

Нажимая на кнопку «Отправить ответ», вы соглашаетесь с нашими пользовательским соглашением, политикой конфиденциальности и политикой о куки

404: Страница не найдена

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

Что я могу сделать сейчас?

Если вы впервые посещаете TechTarget, добро пожаловать! Извините за обстоятельства, при которых мы встречаемся. Вот куда вы можете пойти отсюда:

Поиск

• Узнайте последние новости.
• Наша домашняя страница содержит самую свежую информацию о Java-разработке.
• Наша страница «О нас» содержит дополнительную информацию о сайте, на котором вы находитесь, TheServerSide.com.
• Если вам нужно, свяжитесь с нами, мы будем рады услышать от вас.

Просмотр по категории

Архитектура приложения

• Когда дизайн REST API превращается из полезного во вредный

  REST может быть непререкаемым стандартом в разработке веб-API, но способствовал ли он чрезмерному доверию? Узнайте, почему другой дизайн …

• Azure Logic Apps: чем они отличаются от AWS Step Functions

  Разработчики могут использовать Microsoft Azure Logic Apps для создания, развертывания и подключения масштабируемых облачных рабочих процессов. Узнайте, как он измеряет …

• 5 способов справиться с проблемами монолитных архитектур

  Тем, кто не может перейти на микросервисы, нужен способ повысить надежность архитектуры. Вот пять способов программного обеспечения…

Качество ПО

• Какие сведения включить в отчет о дефекте программного обеспечения

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

• ИИ может исправить болевые точки разработчиков кода GitHub

  Поиск кода GitHub помогает разработчикам запрашивать сложные кодовые базы. Но инструмент мог бы выиграть от более адаптированных результатов и лучшего …

• Разработчики гарантийной компании получают ускорение бессерверных вычислений

  Компания, увязшая в коде AWS CDK, устранила узкие места бессерверной разработки с помощью DevZero, что дает разработчикам собственные . ..

Облачные вычисления

• Начните работу с Amazon CodeGuru с помощью этого руководства

  Amazon CodeGuru проверяет код и предлагает улучшения пользователям, которые хотят сделать свой код более эффективным, а также оптимизировать …

• Упростите управление несколькими облаками с помощью 5 лучших практик

  Внедрение надежных методов управления несколькими облаками может смягчить проблемы и обеспечить безопасность. Ознакомьтесь с передовыми практиками и инструментами…

• Основные проблемы с производительностью в облаке, тормозящие работу корпоративных приложений

  Рабочие нагрузки с жесткими требованиями к задержке, пропускной способности, доступности или интеграции, как правило, работают лучше и стоят меньше, если…

Безопасность

• Rapid7: Злоумышленники используют уязвимости «быстрее, чем когда-либо»

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

• Основные преимущества инструментов SOAR, а также возможные подводные камни, которые следует учитывать

  Чтобы обеспечить успешное внедрение, ИТ-руководители должны понимать преимущества инструментов SOAR, а также потенциальные недостатки. …

• Взлом LastPass связан со взломом домашнего компьютера инженера

  LastPass заявил, что злоумышленник взломал домашний компьютер сотрудника, чтобы получить доступ к корпоративному хранилищу паролей и украсть ключи дешифрования …

ПоискAWS

• AWS Control Tower стремится упростить управление несколькими учетными записями

  Многие организации изо всех сил пытаются управлять своей огромной коллекцией учетных записей AWS, но Control Tower может помочь. Сервис автоматизирует …

• Разбираем модель ценообразования Amazon EKS

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

• Сравните EKS и самоуправляемый Kubernetes на AWS Пользователи

  AWS сталкиваются с выбором при развертывании Kubernetes: запустить его самостоятельно на EC2 или позволить Amazon выполнить тяжелую работу с помощью EKS. См…

Javadocs | Документация IntelliJ IDEA

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

Комментарии к документации также доступны в JavaScript, Python, Ruby, PHP и Kotlin.

Для комментариев к документации IntelliJ IDEA обеспечивает завершение, которое включено по умолчанию.

Информацию о том, как отключить эту функцию, см. в разделе Отключение автоматических комментариев.

Добавление Javadoc с помощью контекстных действий

Для комментариев к методу новая заготовка комментариев содержит необходимые теги (теги @param для каждого параметра метода, @return или @throws ).

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

Информацию о том, как документировать код Kotlin, см. в документации Kotlin.

Отключить автоматические комментарии

Исправить Javadoc

Если сигнатура метода была изменена, IntelliJ IDEA выделяет тег, который не соответствует сигнатуре метода, и предлагает быстрое исправление. Нажмите Alt+Enter , чтобы применить исправление.

Вы также можете обновить существующий комментарий javadoc, чтобы учесть изменения в объявлении, используя действие Fix doc comment:

1. Поместите курсор в класс, метод, функцию или поле и нажмите Ctrl+Shift+A .

2. Введите fix doc comment и нажмите Введите .

Вы можете использовать действие Fix doc comment, чтобы добавить отсутствующую заготовку документации с соответствующими тегами: поместите курсор в класс, метод или функцию и вызовите действие.

Визуализация Javadocs

IntelliJ IDEA позволяет отображать Javadocs в редакторе. Визуализированные комментарии легче читать, и они не перегружают код дополнительными тегами.

Щелкните в поле рядом с необходимым комментарием к документации (или нажмите Ctrl+Alt+Q ), чтобы переключить визуализированный вид; нажмите, чтобы отредактировать комментарий.

Визуализированные документы Javadocs позволяют вам щелкать ссылки, чтобы переходить на указанные веб-страницы или просматривать краткую документацию по указанным темам.

Чтобы изменить размер шрифта, щелкните правой кнопкой мыши Javadoc в редакторе и выберите «Настроить размер шрифта» в контекстном меню. Обратите внимание, что отображаемые комментарии используют тот же размер шрифта, что и всплывающее окно быстрой документации.

Визуализация Javadocs по умолчанию

Можно настроить IDE таким образом, чтобы Javadocs всегда отображались в редакторе.

• Щелкните правой кнопкой мыши значок в поле ( или ) и включите параметр «Визуализировать все».

  В качестве альтернативы в диалоговом окне «Настройки» Ctrl+Alt+S выберите «Редактор | Общие | Внешний вид и включите параметр Отображать комментарии к документации.

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

Создание ссылки на Javadoc

IntelliJ IDEA предоставляет утилиту, позволяющую создавать ссылку на Javadoc для вашего проекта.

1. В главном меню выберите Инструменты | Сгенерировать JavaDoc.

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

   Выходной каталог является обязательным полем: вы не можете создать файл Javadoc, пока он пуст.

3. Используйте ползунок, чтобы определить уровень видимости элементов, которые будут включены в сгенерированную документацию. Выберите один из следующих вариантов:

   • Частный: чтобы включить в ссылку все классы и элементы.

   • Пакет: включает все классы и участников, кроме частных.

   • Protected: включает общедоступные и защищенные классы и члены.

   • Публичные: включать только открытые классы и членов.

4. Вы можете указать локаль (например, en_US.UTF-8 ), аргументы командной строки и максимальный размер кучи.

5. Нажмите OK, чтобы сгенерировать ссылку.

Диалоговое окно «Укажите создание области JavaDoc»

Инструменты | Диалоговое окно «Создать JavaDoc» вызывает утилиту JavaDoc. Элементы управления диалога соответствуют опциям и тегам этой утилиты.

Пункт	Описание
Создать область документа Javadoc	Используйте эту область, чтобы указать подмножество файлов, папок и пакетов, для которых должен быть создан документ JavaDoc. Этой областью может быть весь проект, недавно измененные файлы, текущий файл, пользовательская область и т. д.
Включить источники тестов	Включить комментарии к документации для теста в сгенерированный документ JavaDoc.
Включить JDK и источники библиотек в -sourcepath	Если этот флажок установлен, то пути к источникам JDK и библиотек будут переданы утилите JavaDoc. Подробную информацию см. в документации.
Включить ссылку на документацию JDK	Если этот флажок установлен, ссылки на классы и пакеты из JDK будут преобразованы в ссылки, что соответствует использованию опции -link утилиты JavaDoc. Этот флажок установлен, только если ссылка на онлайн-документацию указана на вкладке «Пути к документации» в настройках SDK. Подробности см. в документации JavaDoc.
Выходной каталог	Укажите полный путь к каталогу, в котором будет храниться созданная документация. Введите путь вручную или нажмите и выберите местоположение в диалоговом окне. Указанное значение передается в -d параметр утилиты JavaDoc. Если указанный каталог не существует в вашей системе, вам будет предложено его создать. Обратите внимание, что если не указан выходной каталог, кнопка OK недоступна.
Уровень видимости	Укажите уровень видимости членов, которые вы хотите включить в сгенерированную документацию: Частный: выберите этот уровень, чтобы включить все классы и элементы. Уровень соответствует -private Параметр JavaDoc. Пакет: выберите этот уровень, чтобы включить все классы и участников, кроме частных. Уровень соответствует параметру -package JavaDoc. Защищенный: выберите этот уровень, чтобы включить только общедоступные и защищенные классы и члены. Уровень соответствует параметру -protected JavaDoc. Публичный: выберите этот уровень, чтобы включить только общедоступные классы и участников. Уровень соответствует -public Параметр JavaDoc.
Создание дерева иерархии	Создание иерархии классов. Если этот флажок снят, параметр -notree передается в JavaDoc.
Создать панель навигации	Создать панель навигации. Если этот флажок снят, параметр -nonavbar передается в JavaDoc.
Создать указатель	Создать указатель документации. Если этот флажок снят, параметр -noindex передается в JavaDoc.
Отдельный индекс для каждой буквы	Создайте отдельный индексный файл для каждой буквы. Если этот флажок снят, параметр -splitindex передается в JavaDoc. Флажок доступен, только если установлен флажок Создать индекс.
@use	Задокументируйте использование класса и пакета. Если флажок установлен, он соответствует параметру -use JavaDoc.
@author	Включите @author абзацев. Если флажок установлен, он соответствует параметру -author JavaDoc.
@версия	Включить @версия абз. Если флажок установлен, он соответствует параметру версии JavaDoc.
@deprecated	Включите информацию @deprecated . Когда флажок снят, параметр -nodeprecated передается в JavaDoc.
список устаревших	Создать список устаревших. Когда флажок снят, -nodeprecatedlist 9Параметр 0129 передается в JavaDoc. Флажок доступен, только если установлен флажок @deprecated.
Языковой стандарт	Введите нужный языковой стандарт.
Другие аргументы командной строки	Введите дополнительные аргументы для передачи в JavaDoc. Используйте синтаксис командной строки.
Максимальный размер кучи (МБ)	Введите максимальный размер кучи в МБ, который будет использоваться Java VM для запуска JavaDoc.
Открыть созданную документацию в браузере	Автоматически открыть созданный документ JavaDoc в браузере.

Просмотр Javadocs в редакторе

В IntelliJ IDEA вы можете просматривать Javadocs для любого символа или сигнатуры метода прямо из редактора. Для этого настройте пути к документации библиотеки или добавьте загруженные Javadocs в IDE. Дополнительные сведения см. в документации по настройке библиотеки.

1. Наведите указатель мыши на нужный символ в редакторе.

2. Поместите курсор на символ и нажмите Ctrl+Q (View | Quick Documentation).

   Нажмите Ctrl+Q еще раз, чтобы открыть эту документацию в окне инструментов Документация.

Для получения дополнительной информации см. краткую документацию

Устранение неполадок

javadoc: ошибка - Неверное имя языкового стандарта: en_US.UTF-8

Очистите поле Языковой стандарт.