Dziś chciałbym poruszyć z Wami problem czytelności kodu. W chwili, gdy nad projektem pracujemy z większym zespołem programistów, warto jest odpowiednio kod komentować, tak, by nie tylko my, ale również cały zespół mógł wykorzystać stworzone przez Nas funkcje bez potrzeby dopytywania lub przeglądania linijek wszelakich funkcji.

Prawidłowe komentowanie kodu to bardzo przydatna umiejętność a jak sami zauważycie, większość IDE – np. NetBeans czy Eclipse – wychodzi nam naprzeciw, odpowiednio formatując blok komentarza.

Rozważmy więc prostą funkcję:

evmipl_mateuszm.pl komentowanie kodu java javadoc

Jak widzicie, funkcja posiada parametr wejściowy oraz zwraca obiekt identycznego typu. Dodatkowo poza danymi wejściowymi i wyjściowymi sama rzuca wyjątek w przypadku pustej listy wektorów. Niestety takie funkcje w Javie zdarzają się bardzo często a omawiany przykład jest bardzo prosty. Mimo to programista, który wykorzystuje naszą funkcję, nie ma na pierwszy rzut oka możliwości ocenienia, jakie operacje na danych są w niej wykonywane.

evmipl_mateuszm.pl komentowanie kodu java javadoc

Jak uniknąć problemów?

Komentowanie kodu w Javie jest wyjątkowo proste. Wystarczy, że tuż nad funkcją wpiszemy „/**” i wciśniemy klawisz ENTER a większość środowisk IDE powinna utworzyć nam odpowiednie elementy komentarza, wliczając w to dane/parametry wejściowe, rzucane wyjątki oraz zwracane dane (dane wyjściowe).

evmipl_mateuszm.pl komentowanie kodu java javadoc

W przygotowanym template możemy wypełnić opis oraz informacje o parametrach funkcji, np.:

evmipl_mateuszm.pl komentowanie kodu java javadoc

Przy dalszym tworzeniu kodu IDE podpowie nam, jaką funkcjonalność ma dana funkcja oraz wskaże parametry wejściowe, wyjątki i zwracane dane.

evmipl_mateuszm.pl komentowanie kodu java javadoc

Mam nadzieję, że wykorzystacie poniższy TIP do usprawnienia swojej pracy. Temat samych opisów funkcji jest dość istotny także przy tworzeniu dokumentacji np. API – o czym mam zamiar Wam jeszcze napisać – udostępnianego publicznie oraz jako element dokumentacji technicznej kodu w przypadku odsprzedaży swojej pracy innym podmiotom.

Komentowanie kodu to strata czasu?

Nie powinniście o komentowaniu kodu myśleć w kategorii straty czasu. Jeśli opisywanie przez Was funkcji, które tworzycie, ma w przyszłości sprawić, że łatwiej będzie Wam utrzymać projekt oraz wprowadzać do niego poprawki i rozszerzenia, to warto jest poświęcić kilka chwil, by w przyszłości nie zgłębiać tajemnicy pisanych wiele miesięcy temu funkcji.

Pozdrawiam,
M.M.