Kod dowolnej aplikacji złożonej odrobinę bardziej niż „Hello World” ma tendencję do stawania się całkowicie niezrozumiałym dla każdego informatyka, który nie jest jego autorem. Ba, po dłuszej przerwie w 90% przypadków staje się chińszczyzną także dla samego autora, i na rozszyfrowanie kodu zużywamy więcej czasu niż wprowadzenie modyfikacji. Jeśli istnieje jakiś sposób, by tego uniknąć, jest nim tylko staranna dokumentacja projektów.

Dokumentacja projektów w RoR

Jeśli jesteśmy programistami wizualnej części aplikacji, czyli tworzymy FrontEnd (HTML, CSS, skrypty), dokumentacja jest w dużej mierze zbędna, ponieważ szybciej i prościej jest skorzystać z FireBuga, żeby dowiedzieć się, w którym miejscu kodu jest poszukiwany przez nas element, oraz jaki kod jest odpowiedzialny za jego położenie czy wygląd. Języki takie jak JavaScript czy CSS są interpretowane przez przeglądarkę, więc narzędzia typu FireBug umożliwiają swobodne poruszanie się po nich tam i z powrotem bez żadnych trudności.

Dokumentacja projektów

Dokumentuj projekt na bieżąco a cały zespół na tym skorzysta.

Sprawa ma się zupełnie inaczej w przypadku kodów odpowiedzialnych za funkcjonalność naszej aplikacji, jak na przykład PHP czy Ruby. Te języki są interpretowane i wykonywane po stronie serwera, przeglądarka otrzymuje zaś przetransformowany kod w HTML – oznacza to, że nie ma fizycznej możliwości, żeby kliknąć w link prawym przyciskiem i sprawdzić, jaką akcję w jakim kontrolerze on załącza.

W tym przypadku dokumentacja projektu to jedyny ratunek dla programisty, który dołącza do projektu po jakimś czasie od rozpoczęcia prac nad nim, albo któremu zostaje zlecone rozszerzenie jego funkcjonalności po kilku miesiącach od zakończenia prac nad aplikacją. Niestety, choć wydaje się to oczywiste, wiele osób dokumentacją projektu wogóle nie zawraca sobie głowy i albo po zakończeniu prac programiści tworzą kilka stron dokumentów „na odpiernicz”, byle tylko coś było, albo nie robią tego wcale, bo „klient i tak nie zrozumie”. Ludzie, dokumentacja projektu nie jest dla klienta! A po co jest?

Dlaczego projekty powinny być dokumentowane?

  1. Bez dokumentacji projektów SCRUM przy projekcie pozostanie w sferze marzeń. Weźmy sobie przykład. Żeby wprowadzić zwinne techniki pracy nad projektem, należy równolegle angażować wszystkich programistów do pracy nad różnymi zadaniami – co jednak, kiedy jeden z programistów otrzyma do wykonania dodanie jakiegoś elementu do zadania, którym zajmował się dotąd inny programista? Powód może być dowolny, choćby urlop albo chorobowe. Co wtedy? Skąd się dowiedzieć, jak rozwiązano zadania nad którymi mamy pracować bez dokumentacji? Bez sprecyzowanych źródeł, z których korzystano wcześniej?Można, ale jest to praca wręcz syzyfowa. Zamiast pół godziny kodowanie może nam zająć kilka dni – a nikt chyba nie lubi takich sytuacji, z właścicielem firmy na czele.
  2. Kolejnym powodem, dla którego warto dokumentować projekty, jest rotacja pracowników. Kierowniku, czy zdażyło Ci się zatrudnić programistę inteligentego i obiecującego, który nie przeszedł okresu próbnego (bo był leniwy, nie wyrabiał się z pracą, nigdy nie był dostępny, albo nie dogadywał się z zespołem)? A zdażyło ci się, żeby ktoś z zespołu po prostu odszedł?Pewnie tak, tylko że znim się ze współpracy z taką osobą zrezygnuje, trochę kodu ten programista napisze. Reszta zespołu też. A na jego miejsce przyjdzie ktoś, kto się wogóle nie orientuje, jak aplikacja wygląda od zaplecza. I wtedy… dokumentacja to jedyna opcja by nowy programista mógł się wdrożyć w zespół.
  3. Mierzalność to podstawa. Czego nie możesz zmierzyć, tego nie możesz naprawić – kiedy projekt się rozrasta i kolejne elementy zaczynają działać, jest to pewna miara efektywności zespołu. Kiedy jednak pracujemy nad zadaniami, które nie są widoczne dla użytkowników, które pracują w tle, ta miara przestaje być efektywna.W tym momencie dokumentacja wykonanych zadań jest dla kierownika projektu świadectwem, że jego zespół nie utknął w miejscu lecz posuwa się naprzód, że nadal jest skuteczny i pracuje.

Co jeszcze? Możecie dopisać w komentarzach 🙂 . Jednak nawet bazując jedynie na powyższych trzech punktach wniosek nasuwa się jeden – dokumentacja projektów jest rzeczą niezbędną. Dokumentować trzeba i należy to, co się robi, a im dokładniej to robimy, tym większa jest korzyść dla nas i naszych klientów.

Inne dobre praktyki programowania

Programować można na różne sposoby, jeśli jednak znane są dobre nawyki, należy je sobie przyswajać, uczyć się ich i na bierząco przy projektach je wdrażać. Na początku iść będzie opornie, lecz w trakcie realizowania kolejnych projektów okaże się, że dobre nawyki owocują, a nasza efektywność wzrasta wykładniczo. Poniżej zamieszczam kilka najważniejszych nawyków programistycznych, które najczęściej są zwyczajnie olewane.

  1. Testy – pisanie testów jest nawykiem rzadkim, jak kwiat paproci, lecz jeśli uda ci się tego nauczyć i przyswoić to w codziennej pracy, bardzo szybko zauważysz efekty, szczególnie przy dużych projektach, a jeszcze bardziej przy projektach zespołowych. Największą jednak efektywność osiąga się, jeśli jedna osoba pisze kod, a druga testy do niego. No ale nie każdy i nie zawsze może sobie na taki luksus pozwolić.
  2. Dokumentacja projektów – jak już wspomniałem wcześniej, najczęściej dokumentacja projektów tworzona jest zwykle nie na bierząco, tylko w kilka dni przed oddaniem aplikacji. Robiona jest powierzchownie i niedokładnie, bez choćby cienia dokładności. Nawyk dokumentowania aplikacji na bierząco, podczas prac nad projektem to coś, co dobry programista powinien opanować i wdrażać najlepiej już od pierwszych, choćby najmniejszych projektów.
  3. Komentarze – często w programach które analizuję są dwie skrajności. Albo komentarzy wogóle brak, albo jest ich więcej niż kodu programu. W obu sytuacjach świadczy to o amatorstwie autora. Jeśli programujesz, poczytaj, do czego służą komentarze i zacznij je stosować tam, gdzie tego sytuacja wymaga. I tylko tam.
  4. Przestrzeganie konwencji nazewnictwa – jeśli chcesz, żeby twój kod był zrozumiały dla innych, a jednocześnie chcesz rozumieć kody programów innych programistów, przestrzegaj norm nazewnictwa. Nie zamierzam tu o nich pisać, możesz zapytać wujka google jak to wygląda w RoR. Nazywanie klas, zmiennych, metod i modeli według stałych i niezmiennych zasad, powoduje, że kod jest bardziej intuicyjny, łatwiej się po nim poruszać, łatwiej zapamiętać nazwy, co powoduje że łatwiej jest go rozszerzać. Nie sprawia też problemu migracja w zespołach i praca nad czyimś programem. Dlatego poczytajcie sobie o tym, jak nazywać zmienne, i przestrzegajcie tego już od pisania „Hello World”. Zawsze i wszędzie.
  5. Język angielski – należy go przyswoić i pisać kod wyłącznie po angielsku. Commit-y na gicie także komentować po angielsku. Dokumentację także polecam tworzyć po angielsku, choć to akurat nie jest wymagane w projektach, które nie mają w założeniach wychodzić na rynki zagraniczne czy angażować zagranicznych specjalistów do ich rozwoju.

Jeśli o czymś zapomniałem, pomóżcie dodając komentarze 😉 . Może to moja wada, a może nie, ale uważam, że jeśli coś się robi zawodowo, należy to robić dobrze. Najlepiej jak się da. W czasach kiedy inżynierów jest więcej niż pszczół, gdzie mnożą się oni jak grzyby po deszczu, znajomość składni nie wystarcza. Znajomość składni w programowaniu to najmniejszy problem. To odpowiednie myślenie i odpowiednie nawyki są wyznacznikiem tego, czy jesteś amatorem czy zawodowcem. I polecam mieć to na uwadze.

 

Pin It on Pinterest

Share This
Sekrety Produktywności

Sekrety Produktywności

DARMOWE szkolenie mailingowe! 10 porad jak zwiększyć produktywność w programowaniu.

Dziękujemy za zapisanie się na kurs. Wkrótce otrzymasz wiadomość email z potwierdzeniem zapisu.

FreshMail.pl