Комментарии 16
Подскажите, что за шрифт на скринах с кодом?
Я бы доки тестов "перенёс" в @DisplayName / @Test(description...) (при возможности).
А вот это: "Да, дока длинная. Она описывает историю развития этого кода." - унёс бы в сообщения комитов. Историю развития всё равно смотришь по комитам. В доке бы оставил только описание действующего алгоритма работы.
Ваша статья, как бальзам на душу. Я думал только наша команда с начала долго и старательно пишет классный код, а потом меняет архитектуру и все переписывает ))
А я пишу доки на тесты.
Но у нас много интеграционных тестов на апи и по доке проще понять, какие кейсы уже протестированы. Особенно помогает, если тесты писал не ты.
Как тут два раза плюсануть?
Здесь даже любители писать документацию вставали на одну сторону баррикад с не-любителями, и утверждали, что уж тесты-то точно самодокументированные. Но тимлид и Сонар были непреклонны. Так и жили.
А разве sonar нельзя настроить, чтобы он не проверял каталог тестов?
Да, можно. Выше я писал в части 1-2 о том что "тимлид и сонар были непреклонны". Возможно эта мысль недостаточно раскрыта. Тимлид был одним из тех, кто настаивал на том, чтобы "писать тесты на все публичное". Позже он, конечно, признал, что это неправильная идея. Но какое-то значительное количество тестов в проекте все же успели покрыть псевдо-доками.
Пользуясь случаем, хотел бы отметить, что тимлид был сильный. Да, он иногда ошибался. Но количество хороших практик, которые он внедрял в проект - было на порядок выше количества плохих практик (таких как "документирование тестов").
Я не одинок во Вселенной!
Но есть небольшой вопрос - поделитесь, какой у вас подход по документированию геттеров, сеттеров, публичных конструкторов и т.п.?
О, это тоже была тема для холивара.
Геттеры/сеттеры и все остальное в DTO, что может генерировать lombok - генерировал lombok. Находились те, кто пытался как-то прикрутить документацию к генерируемому коду. К счастью, их попытки не увенчались успехом. И сонар был настроен так, чтобы не проверять сгенерированный "ломбочий" код. При настройке сонара нас сильно выручила концепция разделения данных и логики. Lombok применялся только в DTO, не содержащих логики. А значит можно было аргументированно дискутировать о том, что в данном классе не нужно документировать методы. Это не снимало с нас обязанности документировать сам класс. Часто в документации на класс была ссылка на аналитику.
Добавлю, что ровно та же история у нас происходила с кодом, сгенерированным org.mapstruct. Там холиваров было меньше - практически сразу все согласились, что тут уж точно код "самодокументированный". Наши мапперы были написаны в стиле пункта 6.2 из этой статьи: https://www.baeldung.com/mapstruct
Отдельно хотелось бы отметить требование писать документацию на всё публичное – все публичные классы и методы. Это требование кажется логичным, если бы не одно “но”. Юнит-тесты тоже публичные, каждый тест публичный.
jUnit позволяет использовать package-private тестовые классы и методы (т.е. без модификатора доступа).
Выше я ответил другому коллеге, повторюсь тут.
Со временем всем, а особенно людям, принимавшим решения о стиле разработки - пришло осознание ошибочности данного подхода (документирование тестов). Но какое-то значительное количество тестов в проекте все же успели покрыть псевдо-доками.
При выходе проекта на финишную прямую такого требования (писать доки на тесты) - уже не было.
Я скорее к тому, что в ситуации "на все публичное надо писать доки" и "не нужны доки на тесты" есть очень простой выход - не делать тесты публичными классами.
И принцип не нарушается и доки на тесты не надо писать.
Иногда для тестов делается определенный тулчейн, например подменяющий "родные" механики - и этот тулчейн хорошо бы задокументировать (особенно если он часто в тестах используется). А как известно, если доки нужно писать, но можно не писать - то доки не будут писать. И с этим статический анализатор может помочь. Но только в том случае, если анализатор не игнорит все, что в тестах происходит.
Как вы контролируете актуальность доков?
Ну т.е. когда у вас есть ENUM с сылкой на ФЗ тут вопросов нет.
Больше интересна ситуация когда у вас есть public метод, который получил описание в первой итерации и потом в него было внесено 10 правок в разных коммитах.
JavaDoc: добро или необходимое зло?