Dokumentacja i komentarze

31.08.2017 AUTOR: Piotr Trybalski

Jeszcze kilka dociągnięć niebieskim długopisem i Spider-man w kratkowanym zeszycie od historii wygląda jak żywy. Spoglądacie na zegarek i minęło już ponad czterdzieści minut. Podnosicie głowy i po drugiej stronie klasy widzicie nauczycielkę od historii, która zamykając swoje książki i dziennik mówi “…i tak właśnie Polska uzyskała niepodległość.”

Odliczacie sekundy do dzwonka, ale słyszycie jeszcze “Przygotujcie proszę na za tydzień referat o Józefie Piłsudskim”. Przez chwilę, niczym sarna w środku lasu, przecinająca drogę przed maską samochodu, przebiega Wam przez głowę dzika myśl, by zapisać sobie koło Spider-mana, treść zadania domowego. Szybko jednak rezygnujecie z tak niedorzecznej czynności mówiąc sobie w duchu “Nie muszę tego zapisywać, będę pamiętać”. Rozlega się upragniony dźwięk szkolnego dzwonka, pakujecie plecak i w pośpiechu biegniecie do szkolnego sklepiku.

Największe kłamstwo dzieciństwa, jak nie nawet życia. “Nie muszę tego zapisywać, będę pamiętać”. Mamy z tym do czynienia w każdej sferze życiowej, idąc do sklepu, w pracy, w domu, rozmawiając ze znajomymi czy oglądając telezakupy. Mimo, że coraz więcej ludzi jest świadomych swojej słabości w tej kwestii, którzy przestali ufać swojej zawodnej pamięci. To jednak masę z nas wciąż się okłamuje każdego dnia.

Zapominalstwo może przysporzyć nam problemy

O ile w kwestiach prywatnych jest to w miarę akceptowalne, o tyle w pracy i w kwestiach służbowych zapominalstwo jest bardzo niepożądaną cechą, której żadne tłumaczenie nie jest w stanie usprawiedliwić.

Zdecydowanie ciężko wymienić zawód, w którym zapominalstwo może być traktowane pobłażliwie, dlatego też nie będę tu stawiał programowania na piedestale podkreślając, że w tym zawodzie jest to szczególnie zły nawyk.

Napiszę tylko jak to wygląda w tej branży, z racji tego, że w każdym zawodzie ta cecha może przynosić inne rezultaty.

Wyobraźcie sobie pisanie dużego i złożonego projektu jako labirynt, który sami projektujecie, i któremu sami budujecie ściany. Wraz ze stawianiem kolejnych ścian, labirynt jest coraz bardziej złożony i trudny do opanowania, a Wy coraz bardziej się w niego zagłębiacie, nie zastanawiając się nad tym jak w ogóle zaczynaliście.

Jeśli chcecie by Wasz labirynt miał kształt równego kwadratu, a nie chaotycznej, bliżej nieokreślonej bryły, to dobrze by było znać konstrukcję labiryntu na pamięć, tak by wiedzieć jak poprowadzić następne ściany. Niestety labirynt jest tak skomplikowany, że niemożliwym jest zapamiętanie go, więc wracacie się na początek by rozeznać się w sytuacji. I tutaj na myśli przychodzi mi znany mem z Władcy Pierścieni, który świetnie oddaje sens przewodni myśli. Gandalf wchodzi do jednego z korytarzy kopalni Morii i nagle się zatrzymuje mówiąc “Nie pamiętam tego miejsca”. Media społecznościowe spopularyzowały to ujęcie do takiego stopnia, ze jego kontekst nadaje się do wielu aspektów naszego życia. W tym przypadku również programowania. Próbując się zorientować w swoim labiryncie zaczynacie na oślep odwiedzać stworzone przez siebie korytarze, sprawdzając dokąd prowadząc.

Jak nie pogubić się we własnym kodzie?

Dokładnie tak samo jest w programowaniu. Piszecie setki, tysiące linijek kodu, dziesiątki podstron, setki poprawek i usprawnień. Wasz projekt rozwija się z dnia na dzień, z tygodnia na tydzień, z miesiąca na miesiąc. Z czasem macie do czynienia z pajęczyną odniesień, niezliczoną liczbą zmiennych, labiryntem zależności. W niektórych miejscach ciężko się połapać co z czym się je. Czytając kod z przed kilku tygodni zastanawiacie się “Wow, jak ja na to wpadłem/wpadłam?”

Jednak prawdziwy ból głowy przychodzi jeśli na czytaniu się nie kończy, a musicie zrozumieć o co w tym wszystkim chodzi. Z dowolnego powodu, musicie coś usprawnić, piszecie nową funkcjonalność, która bezpośrednio się odnosi do tego co napisaliście wieki temu, czy po prostu macie taki kaprys. Wtedy zaczyna się próba interpretacji kodu i zastanawianie się co autor miał na myśli. To potrafi być irytujące, frustrujące, a co najgorsze to spowalnia tempo pracy, ponieważ zamiast pisać kolejne linijki kodu, próbujecie rozgryźć własne wypociny.

Można tego wszystkiego uniknąć pisząc komentarze do swoich skryptów, opisując w miarę dokładnie i szczegółowo jaka jest ich rola i rezultat. Prawie każdy edytor kodu pozwala na pisanie komentarzy, co w opisanych sytuacjach jest rzeczą zbawienną. Jest to instrukcja  działania, którą zostawiacie sami sobie na przyszłość na temat rzeczy, o których z czasem zapomnicie i jest to raczej nieuchronne.

Dobrą sprawą jest też pisanie dokumentacji, czyli dokumentu który w opisowy sposób tłumaczy sens i działanie wszystkich elementów projektu. Zachowując jakąś chronologię i spis treści szybko będziecie w stanie się połapać w tym, co robiliście kiedyś bez tracenia czasu na zabawę w programistycznego detektywa.

Podsumowanie

Tutaj cały czas mowa o sytuacji gdy piszecie własny projekt. To dobry wstęp do systematyzowania sposobu pracy. Na etacie może się to okazać wymagane i niezbędne we współpracy z innymi programistami, którzy nie znając historii Waszego skryptu muszą się szybko połapać o co w nim chodzi.
Wydawałoby się, że to rzecz nieistotna, zbędna biurokracja, a jest to ważniejsze niż by się pozornie wydawało. Im szybciej wejdzie Wam to w nawyk, tym lepiej dla Was i Waszych przyszłych współpracowników.

Artykuł powstał dzięki:

Coders Lab

Łącząc doświadczenie edukacyjne ze znajomością rynku pracy IT, Coders Lab umożliwia szybkie i efektywne zdobycie pożądanych kompetencji związanych z nowymi technologiami. Skupia się się na przekazywaniu praktycznych umiejętności, które w pierwszej kolejności są przydatne u pracodawców.

Wszystkie kursy odbywają się na bazie autorskich materiałów, takich samych niezależnie od miejsca kursu. Dzięki dbałości o jakość kursów oraz uczestnictwie w programie Career Lab, 82% z absolwentów znajduje zatrudnienie w nowym zawodzie w ciągu 3 miesięcy od zakończenia kursu.


CONNECTIS_

+48 22 222 5000
[email protected]

Złota 59
00-120 Warszawa

CONNECTIS_ jest spółką technologiczną świadczącą usługi z zakresu outsourcingu specjalistów, zespołów projektowych oraz procesów IT.


CONNECTIS_
łączy wyjątkowe doświadczenie, kompleksową znajomość branży oraz kompetencje specjalistów z klientami, aby pomóc im usprawniać projekty informatyczne i zwiększać wydajność procesów biznesowych.

Współpracujemy na szeroką skalę z liderami branżowymi w całej Europie z sektora m.in. finansowego, IT, konsultingowego, ubezpieczeniowego, energetycznego oraz telekomunikacyjnego. Codziennie wspieramy ich ponad 350 specjalistami w strategicznych projektach informatycznych.

Do góry!

Polecane artykuły

28.09.2020

Jak efektywnie kosztowo zapewnić organizacji stały dostęp do najnowocześniejszych rozwiązań ...