Kod jako dokumentacja, nie tylko dla Java

Kod jako dokumentacja.

Dlaczego bez dokumentacji?
Czy jest to praktykowalne?
Bez tomów pięknych opisów?
Czy po czasie będę w stanie rozumieć o co chodzi w kodzie?

Martwa dokumentacja lub jej całkowity brak
Jako deweloper pewnie miałeś do czynienia z obiema sytuacjami:
1. brak dokumentacji, chaos, nikt nie wie o co chodzi
2. stara dokumentacja, kolega wie lepiej, nikt nie chce zmieniać dokumentacji

Jeśli chodzi o pierwszy punkt to polecam inny artykuł na temat metod Scrum (jako podejście agile):
Szybkie wprowadzenie do SCRUM. Ograniczenie zakresu pracy, lub lepiej fokusu, do 1-3 tygodni wyklucza potrzebę dokumentacji w sensie gruba książka czarnoksiężnika. Oczywiście opis ważnych funkcji jest pomocny.

Punkt drugi to typowy efekt długiego, klasycznego projektu: piękna dokumentacja gnijąca w czasie.

Kod jest żywy – dokumentacja też musi być żywa
Rozwiązanie jest całkiem proste: BDD czyli Behavior-driven development.
BDD jest rozwinięciem TDD :)
Piszesz test, który jednak w porównaniu do normalnego testu, jest czytelny dla użytkownika (nie-technika).
Ma to duże zalety.
Po pierwsze kod nie jest dla dewelopera lecz jego celem jest rozwiązanie problemu biznesowego.
Klient powinien zdefiniować jak ma funkcjonować system. Powinien określić warunki oraz wyjątki.
Znając warunki piszemy test „ludzkim głosem”, czyli np.
Jako Janek, jak wpłacę 20PLN to mój stan konta zwiększy się z 100PLN do 120PLN.
Tak pisane testy są łatwiejsze także do czytania dla deweloperów.
Ja używam narzędzia Concordion, które generuje raporty w postaci HTML. Polecam.

Dokumentacja będzie się zmieniała razem z kodem.
Nie należy oczywiście zamienić testów jednostkowych (ang. unit test) na specyfikacje. Techniczne testy niech pozostaną widoczne dla techników.

Czysty kod … czyta się jak książkę
Kod, który:
– jest dobrze podzielony
– metody odpowiadają za 1 (jedną) funkcjonalność
– maja sensowne nazwy (SUPER WAŻNE .. i równie ciężkie)
– posiada testy
czyta się bez dokumentacji (javadoc) dostatecznie dobrze.
Jak masz testy to nie masz strachu aby coś zmieniać, gdyż testy są po to aby pokazać czy czegoś nie zepsułeś.
Nie masz testów? Pracujesz ze starym kodem (ang. legacy code)?
Napisz na wstępie testy do istniejącego kodu. W ten sposób go zrozumiesz.
Potem dokonaj refaktoringu.
Używaj czytelne nazwy na zmienne, metody i klasy.
Czasy gdzie liczniki miały i, x i y to przeszłość. Co to oznacza?
Zamiast i użyj np. liczbaUzytkownikowProduktu.
W pierwszym przypadku za każdym razem musisz pomyśleć o co chodziło. W drugim przypadku to po prostu czytasz.

Mam nadzieję, iż te dwie wskazówki pomogą Ci dokumentować pisząc kod :)

Podoba Ci się ten wpis? Kliknij reklamę poniżej – dzięki za wsparcie!

Informacje o @albgorski

Od 1999 roku profesjonalnie zajmuję się rozwijaniem oprogramowania. Głównie Java, ale także Groovy, PHP, HTML, JavaScript oraz Adobe Flex. Fascynują mnie metody wymiany danych, ich przechowywania oraz dostępowania. Jestem WIELKIM zwolennikiem Clean Code, TDD oraz agilistą (może lepiej lean-istą). Ekosystem Java dostarcza WIELE świetnych frawework-ów i bibliotek, a społeczność miłośników języka Java jest najlepsza pod słońcem :)
Ten wpis został opublikowany w kategorii agile, groovy, inżynieria opogramowania, java, scrum, test i oznaczony tagami , , , , , , , . Dodaj zakładkę do bezpośredniego odnośnika.

Możliwość komentowania jest wyłączona.