🦢

Писать или не писать

Писать

  • Одного названия метода, класса или поля может быть недостаточно для того чтобы описать его предназначение.
  • Написать javadoc, поясняющий значение поля или функционал метода, проще и быстрее, чем рефакторить код с неизвестными последствиями.
  • Прочитать javadoc быстрее, чем разобраться во внутрянке метода.
  • Javadoc’и предоставляют возможности для создания кросс-ссылок между различными местами кодовой базы.
  • Для тех, кто не пишет javadoc’и над методами с пометкой @Deprecated, приготовлен отдельный котел в аду.

Не писать

  • Декомпозируй, разбивай классы и методы на маленькие понятные кусочки и будет тебе щАстье.
  • Javadoc’и приходится поддерживать. Рано или поздно javadoc тебя обманет.

Правила

По результатам обсуждения были сформулированы правила, определяющие где нужно писать javadoc’и:

Где писать

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

Где не писать

  • Над методами репозиториев / DAO-классов. Их функционал должен быть очевиден. При использовании Spring Data название метода полностью описывает логику извлечения данных.
  • Над методами REST контроллеров. Их функционал должен быть полностью описан с помощью OpenAPI спецификации.

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

Javadoc’и в тестах

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

Для описания тесткейса должна использоваться аннотация @DisplayName.

На каком языке писать javadoc’и?

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

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

Пасхалочка

В исходниках Spring Data можно увидеть javadoc’и с тэгом @soundtrack. Такие тэги оставлял Оливер Герке и указывал там треки своей музыкальной группы и своих любимых исполнителей. Например: DeferredRepositoryInitializationListener.java

Существует плагин для Intellij IDEA, интегрирующийся со Spotify и подставляющий текущий проигрываемый трек в тэг. К сожалению, работает такой плагин только на MacOS.