Komentarze i samodokumentujący się kod | Kurs Java

Komentarze

Co to 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 dwa typy komentarzy: blokowe oraz do końca linii.

  • do końca linii
    Komentarz do końca linii

    Komentarz do końca linii

  • blokowe – czyli takie, które mogą zawierać kilka linii
    Komentarz blokowy

    Komentarz blokowy

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.

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

Samodokumentujący się kod

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 drugiego komentarza, jako koniec całego bloku, a pozostały fragment spowoduje błąd.

 

Zagnieżdżony komentarz blokowy

Zagnieżdżony komentarz blokowy

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ą

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

Pseudokod

Programista – Pytania rekrutacyjne

Lista pytań rekrutacyjnych, które pozwolą przygotować Ci się na rozmowę kwalifikacyjną.

2 komentarze
Share:

2 Comments

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *