Должны ли тесты JUnit быть javadocced?

Question

У меня есть несколько тестовых примеров JUnit, которые в настоящее время не документированы комментариями Javadoc.

Остальная часть моего кода задокументирована, но мне интересно, стоит ли вообще документировать эти тесты.

Answer 1

Если цель теста очевидна, я не буду документировать ее.

Если это неочевидно, потому что имеет дело с какой-то непонятной ситуацией - или если я хочу сослаться на конкретную ошибку, например - в случае в этом я добавлю документацию. Хотя я не документирую исключения и т.д. - просто краткое описание метода. Это случается относительно редко. Я с большей вероятностью добавлю документацию для вспомогательных методов, используемых в нескольких тестах.

Answer 2

Я не нахожу никакого значения в javadocing тестовых случаях. Я просто делаю имя метода достаточно наглядным, чтобы знать цель теста.

В Ruby я знаю, что есть инструменты для создания документа по названию тестов, но я не видел ни одного из них в Java.

Answer 3

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

Answer 4

Если рассматривать тесты как документацию, не имеет смысла «документировать документацию». Название каждого теста уже само по себе должно описывать, какова цель тестов - каково поведение, определяемое этим тестом.

Используйте длинные описательные имена для тестов и сделайте код теста максимально читабельным.

Например, посмотрите на контрольные примеры в этом проекте . Делает ли кто-нибудь из них что-то не очевидное, глядя на название тестов и тестовый код?

Только в некоторых редких случаях, когда код теста неясен, комментарии необходимы в тестах. Например, если вы тестируете многопоточный код, а тестовый код делает странные вещи, чтобы убедиться, что тестовый код выполняется в правильном порядке. Но даже в этих случаях комментарий является извинением за то, что он не написал более чистый тестовый код.

Answer 5

Я не понимаю, почему вы должны относиться к тестам иначе, чем ваш производственный код в отношении комментариев.

Answer 6

Я думаю, что для javadoc важно, в каких условиях проходят тесты.

Answer 7

Является ли ересь предположением, что комментарии к коду являются антишаблоном? Я согласен с приведенными выше ответами, в идеале ваш код должен быть достаточно описательным, чтобы на него можно было положиться без комментариев. Это особенно верно, если вы находитесь в (корпоративной) среде, где люди, как правило, обновляют код без обновления комментариев, поэтому комментарии могут вводить в заблуждение.

Answer 8

черт возьми, да. даже если это просто ...

создать заказ, редактировать заказ, сохранить, загрузить и проверить это.

Если это действительно простой тест, то, возможно, нет.

Я считаю, что при изменении кода иногда причина теста не очевидна, как это было раньше.

Answer 9

Возможно, вы могли бы попросить кого-то, кто не совсем знаком с вашим кодом, дать вам быстрый отзыв о том, легко ли ваши тесты понятны, как они есть.

В компании, в которой я работаю, мы стараемся дать нашим тестам описательные имена и сложность документа, но зачастую трудно понять, что это "правильно". с первым проектом, потому что вещи, которые очевидны для разработчика, не всегда очевидны для других.

Тесты обрабатываются как код и представляются как часть процесса рецензирования, поэтому наша (небольшая) команда может прокомментировать, насколько легко понять тест или нет.

Если тест немного сбивает с толку, мы можем соответствующим образом обновить название или документацию, и у нас будет более точная оценка того, что работает, а что нет.