Pisanie komentarzy do dokumentu Java w testach jednostkowych

Moim zdaniem same przypadki testów jednostkowych służą jako dokumentacja kodu. Moja firma chce, żebym napisał szczegółowe komentarze w dokumentacji Java na górnej części przypadków testów jednostkowych. Czy to konieczne? Czy piszesz takie komentarze?

unit-testing documentation

— Vinoth Kumar CM
źródło

zakładając, że kod testowy jest dobrze napisany i czytelny, podstawową wartością tego rodzaju komentarza w kodzie testowym jest deklaracja intencji. Może to być bardzo cenne dla recenzentów kodu, nawet ciebie za lata, ponieważ pozwala ci oceniać napisany kod robi to, co powinien, lub testuje to, co powinien przetestować. Po drugie, możesz użyć systemów takich jak JAVADOC lub nawet prostego skryptu, aby zeskrobać nazwy testów i komentarze z kodu, aby utworzyć szybką dokumentację na temat tego, jakie testy masz i co robią.

— Chuck van der Linden

Odpowiedzi:

To, co robię, to komentarz JAVADOC:

klasa wskazująca, która klasa jest testowana jednostkowo (nawet jeśli powinno to być oczywiste, ponieważ najlepsza praktyka na ten temat sugeruje, że nazwą przypadku testowego powinna być nazwa klasy + „Test” lub + „TestCase”). Odbywa się to za pomocą komentarza JAVADOC {@link XXXClass}
metody wskazujące, która metoda jest testowana ({@link XXXClass # method1}). Czasami muszę mieć wiele metod testowych dla jednej metody klasy, aby poprawnie przetestować wszystkie ścieżki. Kiedy to się dzieje, piszę jedną dodatkową linię, podając ścieżkę, którą testuję w środku (ale nigdy nie zbaczam z mojej konwencji jednowierszowej)

Poza tym nie ma innego komentarza. Aby zwrócić ich uwagę gdzie indziej, możesz użyć czegoś takiego jak Cobertura, aby wygenerować ładną grafikę pokrycia kodu i uszczęśliwić ich w ten sposób :-)

Uwaga dodatkowa: mam na myśli przypadki testów jednostkowych, jeśli mówimy o przypadkach testów integracyjnych, to jeden lub dwa kolejne wiersze wyjaśniające, co się dzieje, mogą być rzeczywiście konieczne ...

— Jalayn
źródło

Wymagania dotyczące dokumentacji dla dowolnego kodu są dość całkowicie uwzględnione w odpowiedziach na to pytanie: Mój szef chce opowiadanego po angielsku wyjaśnienia naszego kodu po angielsku

Jako podsumowanie odpowiedzi zobaczysz tam: „To zależy od twojej sytuacji”. Są przypadki, w których jest to uzasadnione (i zachęcane), a inne są stratą czasu.

— Blueberryfields
źródło

Komentarze Javadoc można wyodrębnić i sformatować w osobnym dokumencie referencyjnym, testy jednostkowe nie. Pamiętaj również, że to, co piszesz słowami, może różnić się od rzeczywistego kodu i zazwyczaj opisujesz słowami rzeczywiste oczekiwane zachowanie. Jednym ze sposobów znajdowania błędów jest porównanie dokumentacji z rzeczywistym kodem, jeśli się nie zgadzają - jest to błąd (w jednym z nich, a czasem - w obu).

Test jednostkowy służy do testowania, a nie do dokumentacji. Używanie testu jednostkowego, ponieważ dokumentacja jest błędna i nie powinna być wykonywana.

— littleadv
źródło

Uważam, że dobry zestaw testów jednostkowych jest niezwykle pomocny w dokumentowaniu kodu. Zapewniają one implementację referencyjną, w jaki sposób czyjś kod powinien być stosowany wraz z dowodem, że zachowuje się poprawnie, gdy kod używany w ten sposób.

— Bill Michell,

@Bill - bez argumentu, jest pomocny. Nie zastępuje właściwej dokumentacji.

— littleadv

Twoja dokumentacja zależy od odbiorców - ale w niektórych przypadkach masz całkowitą rację.

— Bill Michell,

Idealnie , testy jednostkowe nie powinny być jedyną dokumentacją systemu - ale w prawdziwym świecie 9 projektów na 10 pracuje ze starszym kodem, gdzie można uznać za szczęście mieć jakąkolwiek dokumentację. W tym przypadku wolę dobry zestaw uruchomionych i pozytywnych testów jednostkowych niż kilka dokumentów, które mogą być całkowicie niezsynchronizowane z rzeczywistym kodem. (Tak, nawet Javadoc może.)

— Péter Török,

@ PéterTörök Tak ... Przeprowadziłem się między kilkoma różnymi pracodawcami, kilkoma bardzo znanymi firmami. Dużo starszego kodu. Jedyne testy jednostkowe w historii - te, które napisałem. Więc miałeś bardzo, bardzo szczęście. Nie zakładaj, że to, co widziałeś, dzieje się wszędzie. A nawet jeśli masz zestaw testów jednostkowych ... Kto powiedział, że są poprawne? Kto powiedział, że pokrywają to, co powinni? Kto powiedział, że oczekiwane wyniki są takie, jakie są? Dlaczego zakładasz, że testy jednostkowe nie są niezsynchronizowane? Tylko dlatego, że „zdają”? Nonsens.

— littleadv