Poetycznie o testach jednostkowych i dokumentacji kodu

//When I wrote this code, only God and I knew how it worked.
//Now, only God knows.

Hej! Dzisiaj chciałbym powiedzieć kilka słów na temat: „Dlaczego warto pisać testy jednostkowe, dokumentować kod i co łączy te dwie rzeczy?”. Z racji, że powstało już wiele dobrych technicznych publikacji na te temat, to ja uderzę w ten sam temat, ale z innej strony (lustra). Tej zabawniejszej, poetycznej.

Miłej lektury ;)

O dokumentowaniu kodu i testach


Tak jak każda historia i ten post ma swoją historię, przyczynę która powołała go do życia. Wszystko się zaczęło kiedy powróciłem pod dłuższej przerwie do swojego tajnego projektu (sekret: kompilatora), który już zapowiadałem na facebooku. Jak się okazało – nie pamiętałem już z tego projektu zbyt wiele. Sama gramatyka języka oraz zasada działania nie należy do najprostszych i najprzyjaźniejszych intuicjom, zatem rozgryzienie tego na nowo byłoby koszmarem, ogólnie powrót najlepiej prezentuje cytat:

Chcę abyście zapamiętali powyższy cytat i mieli go w głowie czytając dalszą część tego wpisu, bo jest on niesamowicie „życiowy” ;)

Szczęśliwym trafem wcześniej napisany kod nie miał być tylko dla mnie (nawet nie docelowo dla Was), był opakowany dodatkową warstwą „historyjek” mających pomóc zrozumieć go osobie, która tego kodu nie pisała (w tym i mnie). Te trudniejsze fragmenty kodu były dość dobrze opisane i byłyby zrozumiałe, gdyby tylko te łatwiejsze, bardziej podstawowe funkcje miały takie same „meta-dane” w postaci komentarzy.

Tutaj przechodzimy do pytania: „czy musimy zawsze rozumieć kod, który napisaliśmy?”. Odpowiedź brzmi „nie*” ;)

Skoro „nie musimy”, to jak możemy zaufać obcemu (naszemu) kodowi, że zwraca poprawne wyniki jeżeli go nie rozumiemy? Tutaj dość sprytnie przechodzimy do kwestii testów jednostkowych, które sprawiają że nawet jeżeli do końca nie rozumiemy co się dzieje w kodzie, to pomagają zweryfikować czy po drobnych modyfikacjach nie zmieniliśmy kodu na gorszy / niepoprawny.

Wiedziony wcześniejszym doświadczeniem (że w każdym momencie wszystko może się zepsuć) pisałem do wcześniej wspomnianego projektu mikro-testy, które pozwalały mi na upewnienie się, że wszystko działa jak powinno. I to nie prawda, że potrzebujemy gigantycznych narzędzi do stworzenia takich testów – wystarczą proste skrypty (przykładowe zaprezentuję w ramach wpisów dotyczących „tajnego” projektu). Dodam jedynie, że większość moich testów to istne sanity-checki (bez żadnych stress testów), pozwalające szybko stwierdzić, czy wciąż działają poprawnie wcześniej napisane funkcjonalności.

Co łączy testy i dokumentację kodu? Odpowiedź jest niezwykle prosta: nasza skleroza ;) Dzięki dokumentacji kodu jesteśmy w stanie stwierdzić do czego służy dana funkcja i co powinna zwracać, a za pomocą testów jednostkowych jesteśmy w stanie sprawdzić faktyczny stan rzeczy oraz dokonywać modyfikacji kodu bez konieczności jego zrozumienia :)

A co z…?


A co z argumentami, które mówią że nie należy dokumentować kodu, bo np. jeżeli jest się jedynym człowiekiem w korpo, który rozumie dany kod, to na pewno nikt cię nie zwolni? Cóż, argument jest dość mocny… ;)

Odpowiedź jednak jest dość prosta: kod warto jest dokumentować, kto wie po jakim czasie przyjdzie nam do niego wrócić i coś naprawić? Jeżeli ktoś jest paranoikiem i nie chce dzielić się dokumentacją (nawet prymitywną), to warto napisać sobie kod np. we flexie, który oczyści nasz kod z komentarzy (btw. napiszemy taki kod w ramach ćwiczenia do „tajnego” projektu.)

Jeżeli chodzi o pisanie testów, to uważam że jednak warto jest mieć jakieś sanity-check’i gdy nasz kod potrafi robić więcej niż jedną rzecz i wynik jednej funkcjonalności, może wpływać na drugą. Jednak wiadomo jak wyglądają rzeczy, które powinno się robić – nie zawsze to robimy ;) (btw2. wkrótce pokażę jak zrobić ultra-prosty we wdrożeniu „framework” pod testy jednostkowe).

Postludium


Wyjątkowo ten wpis zrobił się bardziej „techniczny” niż zazwyczaj, ale liczę że moja historyjka zachęci chociaż parę osób do pisania dokumentacji kodu oraz tworzenia małych testów jednostkowych (pomijam reklamę przyszłego projektu).

Jeżeli macie coś do dodania, to śmiało piszczcie w komentarzach poniżej :) Tradycyjnie zachęcam także do śledzenia bloga przez social-media (panel po prawej).

Do przeczytania już niedługo!

C0d3 0n!


  • Krystian Kwiatkowski

    Czesc, do dodania nie, raczej chodzi o caly wpis, gdzie mowisz, ze warto dodawac komentarze/dokumentacji, by polapac sie po dluzszym czasie, co robi dana funkcja/kod. Czy uwazasz, ze to takze przydane gdy Twoje nazwy zmiennnych mowiac, do czego one sluza?

    • Komentowanie zmiennych raczej ma średni sens, co innego „magicznych” wstawek kodu – to je miałem głównie na myśli gdy mówię o komentowaniu kodu ;)

      • Krystian Kwiatkowski

        Ok, dziekuje bardzo :)