Nie mogę policzyć, ile razy czytam stwierdzenia w duchu „testy jednostkowe są bardzo ważnym źródłem dokumentacji testowanego kodu”. Nie przeczę, że są prawdziwe.
Ale osobiście nigdy nie używałem ich jako dokumentacji. W typowych ramach, których używam, deklaracje metod dokumentują ich zachowanie i to wszystko, czego potrzebuję. Zakładam, że testy jednostkowe wykonują kopię zapasową wszystkich informacji zawartych w tej dokumentacji, a także prawdopodobnie więcej wewnętrznych elementów, więc z jednej strony duplikuje dokumentację, z drugiej strony może dodać coś, co jest nieistotne.
Pytanie brzmi: kiedy testy jednostkowe są wykorzystywane jako dokumentacja? Kiedy komentarze nie obejmują wszystkiego? Przez programistów rozszerzających źródło? A co ujawniają, co może być przydatne i istotne, czego sama dokumentacja nie może ujawnić?
źródło
Odpowiedzi:
NIE są one absolutną dokumentacją referencyjną
Pamiętaj, że wiele z poniższych uwag dotyczy również komentarzy, ponieważ mogą one zsynchronizować się z kodem, na przykład testy (choć jest to mniej egzekwowalne).
Ostatecznie najlepszym sposobem na zrozumienie kodu jest posiadanie czytelnego działającego kodu .
Jeśli w ogóle możliwe i nie pisanie na stałe sekcji kodu niskiego poziomu lub szczególnie trudne warunki byłyby konieczne, dodatkowa dokumentacja będzie miała kluczowe znaczenie.
ALE WCIĄŻ SĄ POMOCNYM Uzupełnieniem dokumentacji
Jednakże, gdy masz wątpliwości co do tego, co robi konkretna klasa, zwłaszcza jeśli są dość długie, niejasne i brakuje komentarzy (znasz tego rodzaju ...), szybko próbuję znaleźć klasy testowe i sprawdzam:
Ponadto, jeśli zostały napisane w stylu BDD , stanowią raczej dobrą definicję kontraktu klasy . Otwórz IDE (lub użyj grep), aby zobaczyć tylko nazwy metod i tada: masz listę zachowań.
Regresje i błędy też wymagają testów
Dobrą praktyką jest także pisanie testów regresji i raportów błędów: naprawiasz coś, piszesz test w celu odtworzenia sprawy. Patrząc na nie, jest to dobry sposób, aby znaleźć odpowiedni raport o błędzie i na przykład wszystkie szczegóły dotyczące starego problemu.
Powiedziałbym, że są dobrym uzupełnieniem prawdziwej dokumentacji i przynajmniej cennym zasobem w tym zakresie. To dobre narzędzie, jeśli jest właściwie używane. Jeśli zaczniesz testować na wczesnym etapie projektu i staniesz się nawykiem, MUSI to być bardzo dobra dokumentacja referencyjna. W przypadku istniejącego projektu o złych nawykach programistycznych, które już przywierają do podstawy kodu, należy postępować z nimi ostrożnie.
źródło
Jedną z interpretacji jest to, że testy jednostkowe są „dokumentacją wykonywalną”. Możesz uruchomić testy jednostkowe na kodzie, a dowiesz się, czy nadal działa tak, jak w momencie, gdy testy zostały napisane jako zaliczone, czy nie. W ten sposób jednostka testuje „dokumentować” funkcjonalność systemu w pewnym momencie, w sposób wykonywalny.
Z drugiej strony rzadko kiedy faktycznie czytam kod testu jednostkowego jako „dokumentację”, aby zrozumieć funkcjonalność. Pojedynczy test jednostkowy jest zbyt umiejscowiony, specyficzny i abstrakcyjny, aby móc wiele powiedzieć o rzeczywistym systemie, który stoi za testowaną klasą.
źródło
Jeśli dokumentacja znaczy chcę coś, aby dowiedzieć się, w jaki sposób kod działa wtedy testy jednostkowe są doskonałymi przykładami jak małe jednostki w pracach kodu zarówno z oczekiwaniami , przypadków brzegowych i błędy (aka bugs ) przypadkach. Ponadto testy mogą zostać utworzone przed napisaniem kodu, co stanowi podstawę tego, co powinien zrobić kod z punktu widzenia biznesu / wymagań.
Czy zastępują dokumentację? Nie.
Czy są przydatnym dodatkiem do dokumentacji? Tak.
źródło
Testy jednostkowe widzę jako:
W pewnym stopniu można je postrzegać jako uzupełnienie istniejącej dokumentacji, ale nie jako dokumentację.
źródło
Odpowiem na twoje pytanie, zadając ci kolejne pytanie.
Jak często pracując z nowym interfejsem API / procedurą wystrzeliłeś pomoc, aby poszukać przykładowego kodu rzeczy, której próbujesz użyć? Jeśli nie przełączysz się na Google, aby wyszukać online próbki kodu?
Właśnie wtedy użyłbyś testów jednostkowych jako dokumentacji.
Podejrzewam, że istnieje kilka powodów, dla których testy jednostkowe nie są wykorzystywane jako dokumentacja, mimo że mogą być doskonałym uzupełnieniem bardziej tradycyjnej dokumentacji:
źródło
TL; DR Testy jednostkowe i komentarze API są komplementarne - niektóre rzeczy najlepiej opisać w kodzie, a inne w prozie.
Testy jednostkowe są głównie przydatne do dokumentowania specjalnych przypadków i warunków brzegowych, które są trudne (i kłopotliwe) do opisania w komentarzach API. Komentarze do interfejsu API są zwykle kierowane do osób, które chcą korzystać z interfejsu API.
Jeśli chcesz zmodyfikować kod, zwykle musisz wiedzieć o wiele więcej, a niektóre z nich trudno umieścić w komentarzach (i te komentarze szybko się zestarzeją). W takim przypadku test jednostkowy działa również jako dokumentacja.
Przykład: masz metodę m,
(a, b)
która wykonuje określone obliczenia. Ze względu na wymagania dotyczące zgodności z poprzednimi wersjami muszą być wprowadzane specjalne przypadkia=0
ia=-1
, ale tylko jeślib
ma wartość NULL. Umieszczenie tego w komentarzu jest skomplikowane, pełne i może stać się nieaktualne, jeśli wymóg zostanie później usunięty.Jeśli wykonasz kilka testów jednostkowych, które sprawdzą zachowanie
m(0, NULL)
,m(-1, x)
uzyskasz kilka korzyści:źródło