Написание комментариев к документации Java для тестовых случаев

На мой взгляд, сами случаи модульного тестирования служат документацией для кода. Моя компания хочет, чтобы я написал подробные комментарии по документам Java в верхней части тестовых случаев. Это нужно сделать? Вы пишете такие комментарии?

unit-testing documentation

— Винот Кумар СМ
источник

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

— Чак ван дер Линден

Ответы:

Что я делаю, так это JAVADOC-комментарий:

класс, указывающий, какой класс тестируется модулем (хотя это должно быть очевидно для меня, поскольку лучшая практика по этому вопросу предполагает, что именем тестового примера должно быть имя класса + "Test" или + "TestCase"). Это делается с помощью {@link XXXClass} комментария JAVADOC
методы, указывающие, какой метод тестируется ({@link XXXClass # method1}). Иногда мне нужно иметь несколько методов тестирования для одного метода класса, чтобы правильно проверить все пути. Когда это происходит, я пишу еще одну строку, в которой указано, по какому пути я тестирую (но я никогда не отклоняюсь от своего однострочного соглашения)

Кроме этого, никаких других комментариев. Чтобы привлечь их внимание в другом месте, возможно, вы могли бы использовать что-то вроде Cobertura для создания красивой графики покрытия кода и сделать их счастливыми таким образом :-)

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

— Jalayn
источник

Требования к документации для любого кода довольно полно отражены в ответах на этот вопрос: мой начальник хочет построчно изложить английское объяснение нашего кода

В качестве резюме ответов вы увидите там: «Это зависит от вашей ситуации». Есть случаи, когда это разумно (и поощряется), и другие, когда это пустая трата вашего времени.

— blueberryfields
источник

Комментарии Javadoc могут быть извлечены и отформатированы в отдельном справочном документе, юнит-тесты - нет. Кроме того, имейте в виду, что то, что вы пишете словами, может отличаться от реального кода, и обычно вы описываете словами фактическое ожидаемое поведение. Один из способов найти ошибки - сравнить документацию с реальным кодом, если они не совпадают - это ошибка (в любом из них, а иногда - в обоих).

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

— littleadv
источник

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

— Билл Мичелл

@ Билл - без аргументов, это полезно. Это не заменяет надлежащую документацию.

— littleadv

Зависит от аудитории от вашей документации - но в некоторых случаях вы определенно правы.

— Билл Мичелл

В идеале модульные тесты не должны быть единственной документацией системы, но в реальном мире 9 проектов из 10 работают с устаревшим кодом, где можно считать удачным иметь какую-либо документацию. И в этом случае я предпочитаю хороший набор запуска и прохождения модульных тестов для нескольких документов, которые могут быть полностью не синхронизированы с реальным кодом. (Да, даже Javadoc может.)

— Péter Török

@ PéterTörök Да ... Я перешел между несколькими работодателями, некоторыми очень известными компаниями. Много унаследованного кода. Единственные юнит-тесты, которые я когда-либо писал. Так что вам очень, очень повезло. Не думайте, что то, что вы видели, происходит везде. И даже если у вас есть набор юнит-тестов ... Кто сказал, что они верны? Кто сказал, что они покрывают то, что должны? Кто сказал, что ожидаемые результаты такие, какие они есть? Почему вы предполагаете, что модульные тесты не синхронизированы? Просто потому что они "проходят"? Бред какой то.

— littleadv