Всем привет!

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

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

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

#java #javadoc #documentation

Всем привет!

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

Еще две мысли о комментариях в коде.

Я как наверное и большинство разработчик - ярый сторонник самодокументирующегося кода.
При этом JavaDoc (KDoc) иногда нужны.
Когда - уже говорил тут https://t.me/javaKotlinDevOps/183

Сейчас хочется добавить еще один позитивный кейс и один признать негативным.

Документация полезна, когда описывает то, чего нет в коде - это понятно.
Но также она полезна, если в нескольких строчках описывает то, что происходит в сложном методе или классе, включающем, скажем, 100-300 строк кода.
В первом случае время прочтения < 1 минуты, во втором прочитать и главное разобраться потребует в разы или на порядок больше времени.
А мы большей частью код читаем, а не пишем. И с учетом потока информации в наше время - код забывается быстро.

И антипаттерн. Ранее я писал, что документирование неочевидных вещей в коде может быть полезно, но это также повод задуматься о рефакторинге.
Сейчас прихожу к мнению, что единственный нормальный комментарий для особого случая - это

// TODO исправить ...

И такой TODO - это code smell в терминологии SonarQube. Не все TODO = code smell, это могут быть и планы на будущее, но в данном случае это точно техдолг.

#documentation

Чем нам конкретно поможет AI?

В данном случае я говорю про помощь в разработке.
Уже писал про написание, а главное поддержание актуальности в документации https://t.me/javaKotlinDevOps/565

Теперь пришло время поговорить про другую важную штуку - TDD.
Что это - Test Driven Development - я думаю знают все.
Знают, но не используют.
Почему?

Особенно хочу подчеркнуть один момент.
С кем бы я не говорил на эту тему - общаясь по работе или на собесах - никто не сказал: "Да фигня этот ваш TDD".
Все знают, все пробовали, но никто не применяет на работе.
Почему?

Ответ видится таким.
Есть задача. Есть ограниченное время. Которое можно потратить на проектирование, кодирование, тесты, отладку, документирование.
Есть такой закон с немного странным названием - закон Паркинсона.
Он гласит: «Работа заполняет всё время, отведённое на неё».
И он применим в ИТ) Увы(

Так вот - что в первую очередь будет выкинуто, чтобы успеть вовремя?
Очевидно документирование и тесты. А оптимизировать тесты (и документацию) проще, если они запланированы на самый конец. И прощай TDD(
Да, все понимают, что тесты - это хороший способ документировать код, это помощь при будущих рефакторингах, это сетка, предотвращающая сползание в легаси.
А TDD - способ гарантировано иметь тесты и тестируемое Java API.
Но ... нет времени.
А далее сервис медленно, но верно превращается в легаси.
Вспоминается грустный анекдот: "... А чё тут думать! Трясти надо!"

К чему я веду?
AI уже берет на себя большУю часть кодирования. AI быстро пишет код.
AI не лень писать тесты.
Точнее как - конечно же лень, любая LLM модель натренирована на получение быстрого результата, это экономика.
Но вопрос решается правильным промтом (контекстом или скилом если быть точным).
И режимом рассуждений (reasoning), предотвращающим забывание агентом правил игры.
Собственно, уже есть фреймворки, например, упомянутый мной https://t.me/javaKotlinDevOps/589 superpowers, в котором TDD встроен как обязательная часть процесса разработки:
brainstorm-планирование-TDD-ревью-commit.

Итог: документирование и TDD - две вещи, которые разработка с AI перемещает из области "надо, но мы не успеваем" в базовую практику.

#ai #tdd #agile #documentation