Написання коментарів java doc для одиничних тестових випадків

На мою думку, одиничні тестові приклади самі служать документацією для коду. Моя компанія хоче, щоб я писав докладні коментарі до java doc у верхній частині тестових примірників. Чи потрібно це робити? Ви пишете такі коментарі?

unit-testing documentation

— Vinoth Kumar CM
джерело

якщо припустити, що тестовий код добре написаний і читабельний, головне значення коментаря такого роду в тестовому коді - це заява про наміри. Це може бути дуже цінним для рецензерівників коду, навіть для вас самих років, оскільки це дозволяє судити про написаний код робить те, що він повинен робити, або тестує те, що він повинен перевірити. По-друге, ви можете використовувати такі системи, як JAVADOC, або навіть простий скрипт, щоб скребити тестові імена та коментарі з коду, щоб створити швидку документацію про те, які у вас є тести та що вони роблять.

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

Відповіді:

Що я роблю, це коментар JAVADOC:

клас із зазначенням того, який клас перевіряється одиницею (навіть якщо це мені очевидно, оскільки найкраща практика з цього питання припускає, що назва тестового випадку має бути назвою класу + "Тест" або + "ТестКаз"). Це робиться за допомогою {@link XXXClass} коментаря JAVADOC
методи із зазначенням того, який метод тестується ({@link XXXClass # method1}). Іноді мені потрібно мати кілька методів тестування для одного методу класу, щоб правильно перевірити всі шляхи. Коли це трапляється, я записую один додатковий рядок із зазначенням того, який шлях я тестую всередині (але я ніколи не відхиляюся від своєї однолінійної конвенції)

Крім цього, жодних інших коментарів немає. Щоб привернути їхню увагу ще десь, можливо, ви могли б використати щось на зразок Cobertura, щоб створити гарну графіку покриття коду та зробити так щасливими :-)

Додаткове зауваження: я маю на увазі тестові приклади, якщо ми говоримо про тести інтеграції, то ще один або два рядки для пояснення того, що відбувається, справді можуть бути необхідними ...

— Джалайн
джерело

Вимоги до документації для будь-якого коду досить повністю висвітлені у відповідях на це питання: Мій начальник хоче розповісти покрокове англійське пояснення нашого коду

Підсумок відповідей ви побачите там: "Це залежить від вашої ситуації". Бувають випадки, коли це розумно (і заохочується), та інші, де це марно витрачання вашого часу.

— чорничі поля
джерело

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

Тест блоку призначений для тестування, а не для документації. Використання тестування одиниць як документації є неправильним, і цього не слід робити.

— littleadv
джерело

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

— Білл Мішель

@Bill - жодних аргументів на це немає, корисно. Це не замінює належну документацію.

— littleadv

Ваша документація залежить від аудиторії - але в деяких випадках ви точно маєте право.

— Білл Мішель

В ідеалі одиничні тести не повинні бути єдиною документацією системи - але в реальному світі 9 із 10 проектів працюють із застарілим кодом, де, можливо, пощастить мати будь-яку документацію. І в цьому випадку я віддаю перевагу гарному набору тестів, що працюють та проходять, через купу документів, які можуть бути повністю синхронізовані з фактичним кодом. (Так, навіть Javadoc може.)

— Péter Török

@ PéterTörök Так ... Я перейшов між декількома різними роботодавцями, деякими дуже відомими компаніями. Багато застарілого коду. Єдиний одиничний тест коли-небудь - те, що я написав. Тож вам дуже пощастило. Не припускайте, що те, що ви бачили, - те, що відбувається скрізь. І навіть якщо у вас є набір одиничних тестів ... Хто сказав, що вони правильні? Хто сказав, що вони покривають те, що повинні? Хто сказав, що очікувані результати такі, якими вони є? Чому ви вважаєте, що одиничні тести не синхронізовані? Просто тому, що вони "проходять"? Дурниці.

— littleadv