Kiedy kod jest przejrzysty

Pisanie kodu to czasami niewdzięczne zajęcie, ale tylko z rzadka. Nieprzyjemnych wrażeń o wiele częściej, jak sądzę, dostarcza czytanie kodu. Jest tak po części pewnie dlatego, że statystycznie programista przeznacza na to zajęcie znacznie więcej czasu (wystarczy policzyć chociażby debugowanie). Innym powodem może być też to, że dokładne zdefiniowanie takiego określenia jak przejrzysty kod okazuje się zaskakująco trudno, bo kategoria ta wydaje się w dużym stopniu subiektywna.

Weźmy na przykład komentarze. Potoczna koderska mądrość mówi nam, że łatwy do zrozumienia kod zapewne posiada dużo komentarzy, bo w końcu jak inaczej opisać zawiłości konstrukcji językowych i bibliotecznych, które się w nim znajdują?… Może to i przekonująca logika, ale ja mam lepszą. Można by przecież liczbę tych zawiłości minimalizować jeśli nie eliminować zupełnie. Kod przejrzysty powinien dokumentować się w zasadzie sam. Wyjątki istnieją, oczywiście, bo zawsze znajdą się jakieś kruczki, haki i inne triki, które można opatrzyć jedynie napisem // Magic. Do not touch. (o ile nie chcemy opisywać ich działania w elaboracie na piętnaście linii). Jeśli jednak większość kodu wygląda “magicznie”, to jego autora należy czym prędzej przeszkolić w bardziej mugolskich technikach programowania :)

Trochę odrębnie od przygodnych komentarzy traktuję wstawki mające służyć na dokumentację do poszczególnych elementów kodu. Tworzenie jej w pełnej formie, z opisem każdego pola, metody i parametru jest nie tylko czasochłonne, ale i w dużej części niezbyt sensowne. Z drugiej jednak strony brak chociaż słowa wzmianki nt. tego, co dana klasa czy metoda w zasadzie robi to zbrodnia popełniona na nieszczęśnikach, którzy potem muszą przedzierać się przez taką terra incognita. Można obyć się bez wiedzy, jak dany element działa, ale informacja o tym, do czego służy lub co ma w założeniu robić jest po prostu niezbędna.

Komentarze, według mnie, to jednak w ostatecznym rozrachunku sprawa drugorzędna. Znacznie ważniejsza – być może nawet pierwszorzędna – zdaje mi się bowiem odpowiednia organizacja na każdym poziomie projektu. Zaczyna się ona od rozmieszczenia funkcjonalności w klasach, modułach i pakietach, a kończy na układzie samych deklaracji w plikach. Ogólna zasada jest tu bardzo prosta: chodzi o to, by elementy podobne i odpowiedzialne za zbliżone zadania były fizycznie blisko siebie. Regułę tę można łamać w przypadkach uzasadnionych i chęć podziału kodu na warstwy (np. logiki i interfejsu) jest na pewno jednym z nich. Często nie da się tego jednak powiedzieć np. o grupowaniu ze sobą w klasie metod o tej samej widoczności zamiast podobnej i/lub zależnej funkcjonalności

Wreszcie, o przejrzystości kodu decydują też wrażenia wzrokowe otrzymywane w czasie jego oglądania. Wpatrywanie się w długie, gęsto zapełnione znakami wiersze o znikomej ilości pustych przestrzeni jest zajęciem męczącym i dlatego powinniśmy oszczędzać go sobie i innym. Stosujmy więc białe znaki, i to rozrzutnie. Spacje, podziały wiersza oraz puste wiersze (a czasami i wcięcia, jeśli język na to pozwala) używane w przemyślany sposób poprawiają wizualny odbiór listingów i jednocześnie poprawiają wspomnianą wcześniej organizację – tym razem na poziomie mikro.

O pożytkach z komentarzy

Kiedy komukolwiek pokazuję fragment napisanego przez siebie kodu, reakcja jest zawsze dość podobna. Można ją streścić jako pytanie: “A dlaczego tu tak zielono?” :)

Faktycznie, dość intensywnie używam komentarzy. Rzeczywiście, nadużywam też stosowania przerw w postaci pustych wierszy. Zgadza się, że dwa wiersze “normalnego” kodu odpowiadają przeciętnie trzem wierszom napisanym przez mnie. Tak, to wszystko prawda. Co mam na swoje usprawiedliwienie?
Otóż… nic :P Wręcz przeciwnie, taki sposób pisania uważam za bardzo pożyteczny, a powodują mną takie oto motywy:

Logo programu doxygen, jednego z darmowych systemów generujących dokumentację techniczną z kodu
• Pierwszy jest dość oczywisty: duża ilość komentarzy ułatwia zrozumienie kodu. Ponadto jeżeli nie są to komentarze pisane ot, tak sobie, lecz zgodnie z pewnym powszechnym standardem, mogą zostać wykorzystane do stworzenia dokumentacji technicznej. Na temat takiej dokumentacji można oczywiście powiedzieć mnóstwo złych rzeczy – na czele z jej małą przydatnością dla samego programisty, który dany kod tworzy. Pozwala ona jednak przynajmniej spojrzeć całościowo na daną klasę/moduł/przestrzeń nazw/bibliotekę/program, zwłaszcza jeśli używany program potrafi też rysować ładne schematy :)
• Poza tym ktoś ładnie powiedział, że komentarze są przydatne, ponieważ są zielone ;] Zdecydowanie lepiej patrzy się na kawałek kodu poprzecinany adnotacjami czy pustymi liniami niż na jednolitą szpaltę wysokości drapacza chmur. Stosowanie separatorów w rodzaju /********/ czy nagłówków opisujących pliki na pewno polepsza czytelność kodu.
  Kiedyś na Warsztacie założyłem sondę na temat zalet komentarzy i wolą większości ten argument został uznany za najważniejszy.
• Po trzecie kod z komentarzami jest zwyczajnie ładniejszy. Naturalnie nie zdadzą się one na wiele, jeżeli ktoś stosuje nazwy w stylu function1, a klawisza Tab używa tylko w połączeniu z Altem :) Szkoda, że tego rodzaju kod widzi się stanowczo za często ;P
• I wreszcie jedna sprawa dotycząca nie samych komentarza, lecz ich pisania. Kiedy programuje się z zamiłowania, nierzadko ma się “natchnienie”, które chciałoby się od razu przełożyć na kod. Jakie są tego skutki, nietrudno się domyślić, bo przecież co nagle to po diable ;) Jeżeli jednak wcześniej poświęci się chociaż chwilę na napisanie komentarza do powstającej funkcji/klasy/itp. to skutek jest zwykle lepszy.

Tak więc, Wysoki Sądzie, z powodu swojego rozwlekłego stylu kodowania nie czuję najmniejszych wyrzutów sumienia i nie postanawiam nawet minimalnej poprawy ;P Co więcej, nie będę się krępował przed propagowaniem swoich poglądów na ten temat każdemu, kto będzie miał (nie)przyjemność oglądać napisany przeze mnie kod :)