Java для автоматизаторов
  • Introduction
  • Java. Введение
    • Java как язык и платформа
    • Установка и настройка
  • Язык Java. Основы
    • Hello World
    • Переменные
    • Типы данных
    • Строки
    • Циклы "while" / "do ... while"
    • Циклы "for"
    • Условный оператор "if / if ... else"
    • Условный оператор "switch"
    • Массивы
    • Задания к главе
  • ООП в Java
    • Классы и объекты
    • Методы
    • Свойства
    • Параметры методов
    • Ключевое слово this
    • Конструктор
    • Модификаторы static и final
    • StringBuffer
    • Метод toString()
    • Метод equals()
    • Наследование
    • Пакеты
    • Интерфейсы
    • Модификаторы Public, Private и Protected
    • Полиморфизм
    • Инкапсуляция
    • Использование обобщений
    • Generics and Wildcards
    • Анонимные классы
    • Исключения
    • Множественные исключения
    • Абстрактные классы
    • Вложенные классы
    • Тип Enum
    • Задания к главе
  • Коллекции
    • ArrayList
    • Linked Lists
    • HashMap
    • Sets (Множества)
    • Sorted Maps
    • Задание порядка в множестве ( natural ordering )
    • Очередь (Queue)
    • Использование итераторов
    • Создание объектов, реализующих интерфейс Iterable
    • Задания к главе
  • Стиль написания кода
    • Структура файла
    • Файлы-исходники
    • Открывающие комментарии
    • Сведения о пакете и импорте
    • Объявление классов и интерфейсов
    • Длина строки
    • Переносы строк
    • Переносы в объявлении методов
    • Переносы в операторе if
    • Переносы в тернарных операциях
    • Виды комментариев
    • Блочные комментарии
    • Однострочные комментарии
    • Комментарии в конце строки
    • Объявления (Декларации)
    • Операторы
    • Пропуски
    • Конвенция именования
    • Задания к главе
  • Работа с файлами
    • Работа с текстовыми файлами
    • Работа с XML файлами
    • Работа с JSON файлами
    • Property-файлы
    • Задания к главе
  • Log4j - система логирования сообщений в Java
    • Начало работы
    • Конфигурационные файлы
    • Стандартные аппендеры
    • Задания к главе
  • Юнит тестирование
    • JUnit vs TestNG. Основные аннотации
    • JUnit vs TestNG. Примеры тестов
      • Exception тесты
      • Ignore тесты
      • Тест с таймаутом
      • Тест сьюты
      • Параметризованные тесты
      • Зависимые тесты
      • Многопоточность
    • Asserts
    • Использование "заглушек" (Mocks)
  • Build инструменты
    • Build инструменты
    • Примеры конфигураций
  • Системы контроля версий. Git
    • Системы контроля версий. Git
    • Git. Установка
    • Git. Основы
    • Git. Основные команды
      • Настройка
      • Работа с репозиторием
      • Работа с удаленным сервером
      • Работа с ветками
Powered by GitBook
On this page
  1. Стиль написания кода

Виды комментариев

У Java программ могут быть два вида комментариев: комментарии реализации и документирующие комментарии. Комментарии реализации, аналогичные комментариям в C++, ограничиваются /.../ и //. Документирующие комментарии (известные как “doc comments”) встречаются только в Java и ограничиваются / *.../. На основе документирующих комментариев с помощью утилиты javadoc могут быть созданы файлы документации в формате HTML.

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

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

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

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

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

Комментарии никогда не должны включать служебные символы, такие как возврат каретки и backspace.

Типы комментариев реализации

Программа может содержать такие стили комментариев реализации, как: "блочный", "однострочный" или "комментарий в конце строки"

PreviousПереносы в тернарных операцияхNextБлочные комментарии

Last updated 6 years ago