Всем привет!

Уже несколько раз упоминал в последних постах JavaDoc\KDoc. Нужен ли он вообще?
Мой ответ: да, но не всегда.
Основной критерий - JavaDoc должен приносить пользу. Т.е. давать дополнительную информацию. Дополнительную к чему?
1) названию модуля
2) названию пакета
3) названию класса\паттерна
4) названию метода или поля

Что это может быть?
1) контракт, как использовать и наследовать класс
2) причины выбора того или иного алгоритма
3) пример использования, его также можно поместить в unit тесты
4) TODO, причины объявления deprecated
5) ссылки на используемые в коде алгоритмы
6) краткое описание бизнес-логики, т.к. разработчики не ходят в wiki\Confluence )))
7) особые случаи использования, неочевидное поведение кода с некоторыми параметрами. Хотя это скорее антипаттерн, само наличие неочевидного поведения - повод подумать про рефакторинг

Почему все же не стоит писать "дежурный" комментарий над классом и публичными методами?
1) на это тратится время
2) главная причина - рефакторинг кода. При рефакторинге обычно меняют имена методов, полей и классов. Иногда забывают. Но если говорить о комментариях - тут все наоборот: иногда их обновляют, но чаще - забывают. И получаем код, на который было потрачено время, но который мало того, что не приносит пользу - так еще и вводит в заблуждение.

#java #javadoc

Всем привет!

Недавно обсуждали с коллегой необходимость JavaDoc\KDoc и в дополнение к высказанным ранее мыслям https://t.me/javaKotlinDevOps/183 возникла еще одна.
Напомню, основная моя идея была такая: массовый JavaDoc бесполезен, он должен быть точечным - там где назначение кода не понятно из наименования.

Немного переобуюсь) Массовый JavaDoc все же может быть полезен. Где? Для для описания монолита. И при одном условии.

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

А условие, точнее 3 условия, такие:
1) при каждой сборке develop ветки должен собираться и выкладываться актуальный JavaDoc. Тут даже мало JavaDoc артефакта, нужен сайт, где его можно прочитать. Например, GitHub Pages\GitLab Pages или аналоги.
2) должна быть точка входа или оглавление, например readme.md.
3) при написании документации и в особенность на ревью кода нужно обращать внимание не на наличие JavaDoc, а на его содержимое

P.S. Но JavaDoc конструкторов - все равно зашквар)

#javadoc #documentation