🦢
Писать или не писать
Писать
- Одного названия метода, класса или поля может быть недостаточно для того чтобы описать его предназначение.
- Написать 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.