Komentarze i samodokumentujący się kod | Kurs Java

Komentarze nie są jak Lista Schindlera. Nie są „czystym dobrem”. W rzeczywistości komentarze są w najlepszym wypadku złem koniecznym – Robert C.Martin

W tym materiale przedstawię Ci ważny, szczególnie dla zachowania czystości kodu temat, jakim są komentarze. Przedstawię Ci dobre praktyki, za jakimi powinno się podążać. Komentarze mogą być pomocne, jednak łatwo można sprawić, że bardziej będą śmiecić nasz kod niż dawać dobro.

Java – Komentarze – wprowadzenie

Z tego materiału dowiesz się:

• Czym jest komentarz?
• Jakie są dobre praktyki pisania komentarzy?
• Czym jest pseudokod?

Java – Czym jest komentarz?

Komentarze to swego rodzaju zapiski programisty w kodzie aplikacji. Ich celem jest przekazanie jakiejś informacji dla siebie samego lub dla innych osób czytających ten kod.

Komentarze są widoczne tylko w kodzie źródłowym i przy kompilacji są pomijane, dlatego nie mają wpływu na samo działanie wynikowej aplikacji. Jednak jest to integralna część każdego programu i nie powinna być pomijana. Dzięki nim można lepiej zrozumieć intencje programisty, co jak w praktyce się okazuje, nie zawsze jest takie oczywiste 🙂

W Javie mamy trzy typy komentarzy:

• jednoliniowe
• blokowe (wieloliniowe)
• dokumentujące (javadoc)

Java – Komentarz jednoliniowy

Komentarz jednoliniowy zaczyna się od dwóch ukośników „//”. Jest uznawany za tzw. komentarz do końca linii. Wszystko, co znajduję się za znakiem podwójnego slash’a nie zostanie wykonane. Nie jest konieczne używanie go od początku linii. Możesz również zastosować taki komentarz po jakimś fragmencie kodu.

Komentarz do końca linii

Java – Komentarz blokowy – wieloliniowy

Komentarz blokowy to taki, który może zawierać kilka linii.

Taki komentarz:

• otwiera znak /*
• zamyka znak */

Java – Javadoc – Komentarz dokumentujący

Komentarz dokumentujący służy do tworzenia dokumentacji i ogólnie nazywany jest komentarzem doc.

Komentarze do dokumentacji umieszczane są pomiędzy /** i */.

Aby stworzyć dokumentację API, musimy należy narzędzia javadoc. Narzędzie JDK javadoc używa komentarzy doc podczas przygotowywania automatycznie generowanej dokumentacji.

Korzystając z IDE – wystarczy wprowadzić /** i nacisnąć enter i javadoc zostanie automatycznie wygenerowany.

Gdy posiadamy już ładnie opisany javadoc, wystarczy najechać kursorem na wywołanie metody, aby móc zobaczyć naszą dokumentację.

W większych projektach, przy których pracuje wielu programistów pisanie javadoc’ów jest bardzo ważne. Taka dokumentacja zdecydowanie ułatwia i przyspiesza pracę, ponieważ unikamy niepotrzebnych rozważań, dotyczących pytań takich jak np. na czym polega działanie danej klasy lub metody.

Javadoc – Tagi

Dobre praktyki stosowania komentarzy

Komentarze służą poprawie czytelności kodu. Dlatego nie powinno się dodawać ich na siłę do każdego fragmentu kodu, a jedynie w miejscach, gdzie czujemy, że przydałoby się jakieś wyjaśnienie.

Pisz samodokumentujący się kod – Twórz „czysty kod” (ang. clean code) 

Idąc krok dalej, można powiedzieć, że gdzie tylko to możliwe komentarze powinny być zastępowane czytelnym kodem, który nie wymaga dodatkowego objaśnienia. Powstaje w ten sposób tak zwany samodokumentujący się kod. Przykładowo, dużo lepiej jest nadać metodzie opisową nazwę niż wyjaśniać w komentarzu, co programista miał na myśli.

Samodokumentujący się kod

Nie zagnieżdżaj komentarzy

Przy stosowaniu komentarzy blokowych należy pamiętać, że nie można ich zagnieżdżać, tzn. jeżeli spróbujemy wstawić jeden komentarz w drugim, to kompilator potraktuje koniec środkowego komentarza, jako koniec całego bloku, a pozostały fragment spowoduje błąd.

Zagnieżdżony komentarz blokowy

Stosuj poprawnie komentarze jednoliniowe

Komentarze do końca linii, jeżeli zostaną wstawione w niewłaściwym miejscu, również mogą powodować kłopoty. Przykładowo, jeżeli zostaną wstawione między instrukcją if a rozpoczynającą klamrą to po zmianie formatowania kodu może dojść do zakomentowania tej klamry i błędów kompilacji.

Komentarz do końca linii przed klamrą

Pseudokod

Dość często spotykaną praktyką jest najpierw pisanie komentarzy, a dopiero na ich podstawie tworzenie właściwego kodu. Powstaje w ten sposób tak zwany: pseudokod – czyli fragmenty kodu pomieszane z komentarzami. Rezygnuje się w nim ze ścisłych reguł składniowych narzuconych przez kompilator na korzyść prostoty zapisu i czytelności. Pomijane są również szczegóły implementacyjne.

Dzięki temu bardzo szybko można spisać algorytm i dopiero w kolejnych krokach po kawałku zamieniać go na właściwą implementację.

Pseudokod

Java – Komentarze – Podsumowanie

W ramach tego materiału dowiedzieliśmy się, czym są i jakie wyróżniamy  rodzaje komentarzy. Bliżej zapoznaliśmy się z dobrymi praktykami pisania komentarzy.  Jeżeli chcesz kontynuować swoją przygodę z Javą i poznać inne struktury, które oferuję ten język programowania – to zapraszam do kolejnego tematu z serii o Javie. Opowiem Ci o zmiennych i typach danych stosowanych w Javie.

➡ ZOBACZ 👉: Zmienne i typy danych

Kierunek Java

W serii o Javie zapoznajesz się z podstawowymi tematami o Javie. Jeżeli chcesz bardziej kompleksowo zagłębić się w temat Javy, poczytać, posłuchać o Javie,  to zachęcam Cię do zapoznania się z moim kursem „Kierunek Java”:

➡ ZOBACZ 👉: Kierunek Java