У меня есть несколько тестовых примеров JUnit, которые в настоящее время не документированы с комментариями Javadoc.
Остальная часть моего кода документирована, но мне интересно, стоит ли даже документировать эти тесты.
Если цель теста очевидна, я не документирую ее.
Если это неочевидно, потому что оно касается какой-то неясной ситуации - или, если я хочу, например, ссылаться на конкретную ошибку, в этом случае я добавлю документацию. Я не документирую исключения и т.д., Но - просто краткое изложение метода. Это происходит относительно редко. Я, скорее всего, добавлю документацию для вспомогательных методов, используемых в нескольких тестах.
Я не нахожу значения в javadocing тестовых случаях. Я просто делаю имя метода достаточно понятным, чтобы знать цель теста.
В Ruby я знаю, что есть инструменты для создания документа из имени тестов, но я не видел ни одного из них в Java.
Независимо от того, javadoc или нет, я думаю, что модульные тесты должны быть обязательно документированы. В тех случаях, когда формальная спецификация не существует, модульные тесты являются наиболее близкими к определению ожидаемого поведения кода. Зарегистрировав тестовые примеры, вы ясно дадите читателю понять, что тестирует тест, и почему он его тестирует.
Когда вы думаете о тестах как документации, не имеет смысла "документировать документацию". Имя каждого теста уже должно само по себе описывать, что является целью тестов - каково поведение, заданное этим тестом.
Используйте длинные описательные имена для тестов и сохраняйте как можно более читаемый тестовый код.
Например, посмотрите в тестовых примерах в этом проекте. Кто-нибудь из них делает что-то, что явно не очевидно, глядя на имя тестов и тестовый код?
Это только в некоторых редких случаях, когда тестовый код неясен, что комментарии необходимы в тестах. Например, если вы тестируете многопоточный код, а тестовый код делает странные вещи, чтобы убедиться, что тестовый код работает в правильном порядке. Но даже в тех случаях комментарий является извинением за то, что он не пишет чистые тестовые коды.
Я не понимаю, почему вы должны рассматривать тестовые примеры иначе, чем ваш производственный код в отношении комментариев.
Я думаю, что это важно для javadoc условий, при которых проходят тесты.
Является ли ересь предположить, что комментарии кода являются анти-шаблонами? Я согласен с приведенными выше ответами, в идеале ваш код будет достаточно описательным, чтобы опираться без комментариев. Это особенно актуально, если вы находитесь в (корпоративной) среде, где люди склонны обновлять код без обновления комментариев, поэтому комментарии становятся вводящими в заблуждение.
ад да. даже если его просто...
создать заказ, отредактировать заказ, сохранить, загрузить и проверить его.
если это действительно простой тест, то, возможно, нет.
Я нахожу, что с изменением кода иногда причина теста не очевидна, как когда-то.
Возможно, вы могли бы получить кого-то, кто не совсем знаком с вашим кодом, чтобы дать вам краткую информацию о том, легко ли ваши тесты понятны, как они есть.
В компании, над которой я работаю, мы стараемся дать наши тесты описательным именам и сложности документа, но часто трудно получить это "право" с первым проектом, потому что вещи, очевидные для разработчиков, не всегда очевидны для другие.
Тестирование обрабатывается как код и представляется как часть процесса экспертной оценки, поэтому наша (небольшая) команда может прокомментировать, легко ли понятен тест или нет.
Если тест немного запутан, мы можем соответствующим образом обновить имя или документацию, и мы уйдем с лучшей оценкой того, что работает, а что нет.