Всем привет!

Недавно обсуждали с коллегой необходимость 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