Всем привет!

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

Как быстрее погрузиться в код?

Речь про существующий микросервис и нового разработчика.
Я уже писал, что JavaDoc (KDoc) не является обязательным для каждого метода\поля или класса (как минимум для бизнес-приложения, общие библиотеки - особый кейс), т.к. документацию никто не читает.
А что же тогда будет документацией? Например, тесты. Их конечно тоже новичок не будет читать на 100%, но во-первых их и так нужно писать, а во-вторых - при рефакторинге падающий тест покажет, что забыли поправить, а в целом любой существующий тест изменяемого класса покажет, как он работает.

А недавно я нашел еще один полезный способ задокументировать микросервис так, чтобы этой "документацией" пользовались.
Начну немного издалека. Есть такая ИТ консалтинговая компания как Thoughtworks. Ну есть и есть, где мы и где консалтинг. Но там работает такой небезызвестный человек, как Мартин Фаулер. Главный научным руководителем https://www.thoughtworks.com/profiles/leaders/martin-fowler
А это внушает некий уровень доверия.
Так вот, компания ведет реестр технологий а-ля техрадар.
И в текущей его версии есть такая штука https://www.thoughtworks.com/en-de/radar/techniques/api-request-collection-as-api-product-artifact
как коллекция API запросов как артефакт продукта.
На самом деле мысль лежит на поверхности, я уже достаточно давно практикую прихранивание запросов в формате IDEA api collection вместе с исходниками в тех проектах, над которыми приходилось работать. Да, над форматом стоит подумать отдельно, возможно Insomnia будет по-универсальнее, зависит от команды и организации. Но сама идея мне очень нравится. Такой документацией точно будут пользоваться.

P.S. Кто ее должен делать - разработчики или тестировщики и нужно ли шарить коллекцию между ними - тоже вопрос для обсуждения. В идеале - думаю, что да.

P.P.S. Да, когда я говорю про артефакт продукта - это значит мало ее сделать, ее нужно поддерживать в актуальном состоянии.

#api #onbording #documentation