Komentarze w kodzie

5.1 Jak pisać komentarze

W Pythonie, jak i w wielu innych językach programowania, można pisać komentarze w kodzie. Komentarze pomagają programistom i innym uczestnikom projektu zrozumieć kod, co jest szczególnie przydatne przy pracy zespołowej i długoterminowej konserwacji programów. W Pythonie istnieje kilka sposobów dodawania komentarzy do kodu.

Komentarze jednoliniowe:

Zaczynają się od znaku #. Wszystko, co następuje po # w tej samej linii, Python ignoruje. Ten typ komentarza jest zwykle używany dla krótkich uwag lub wyjaśnień do określonej linii kodu. Przykład:

# To jest komentarz jednoliniowy
print("Hello, World!") # Wyjaśnienie działania funkcji

Komentarze wieloliniowe:

W Pythonie oficjalnie nie ma specjalnej składni dla komentarzy wieloliniowych, ale można je stworzyć za pomocą kilku komentarzy jednoliniowych lub używać potrójnych cudzysłowów, chociaż to ostatnie jest w rzeczywistości stringiem wieloliniowym, nie wykonywanym jako kod. Przykład:

# To jest przykład komentarza wieloliniowego # Każda linia zaczyna się od znaku #
      

lub:

""" To jest string wieloliniowy, który może być użyty jako komentarz. Python interpretuje go jako ciąg znaków, ale nie robi nic z tym ciągiem, jeśli nie jest przypisany do zmiennej lub używany w wyrażeniu. """ 
      

5.2 Dlaczego pisać komentarze

Używanie komentarzy w kodzie zwiększa jego czytelność, ułatwia utrzymanie i aktualizację, a także sprzyja bardziej efektywnej współpracy w zespołach. Komentarze powinny być zwięzłe, ale informacyjne i aktualne, aby służyć jako przydatna dokumentacja kodu i nie zaśmiecać go zbędnymi informacjami.

Docstrings:

To ciągi, które zazwyczaj umieszcza się na początku modułów, klas, metod i funkcji w celu opisania ich przeznaczenia. Są one zamykane w potrójnych podwójnych cudzysłowach i mogą być używane do automatycznego generowania dokumentacji.

Przykład:

def add(a, b):
""" Funkcja do dodawania dwóch liczb. :param a: pierwszy składnik :param b: drugi składnik :return: suma a i b """
    return a + b

W świecie programowania czasami deweloperzy dodają do swojego kodu komentarze, które nie tylko służą jako wyjaśnienia, ale i wywołują uśmiech. Oto kilka przykładów zabawnych komentarzy, które można spotkać w kodzie:

Przykład 1

 

            # Wyjaśniłbym, co tu się dzieje, ale nawet mnie to już nie jest jasne.
        

Przykład 2

 

    # Jeśli to nie działa, to wina kogoś innego.

Przykład 3

 

    # Przyszedłem, zobaczyłem, naprawiłem... i zepsułem.

Przykład 4

 

    # Kiedy to pisałem, tylko ja i Bóg wiedzieliśmy, jak to działa.
    # Teraz wie tylko Bóg.

Te komentarze mogą dodawać lekkości i humoru do procesu tworzenia oprogramowania, czyniąc bazę kodową mniej monotonną. Mogą także służyć jako przypomnienie, że tworzenie oprogramowania to kreatywny i ludzki proces.

5.3 Szybkie komentowanie kodu

W PyCharm możesz szybko zakomentować lub odkomentować kod, używając skrótów klawiszowych. Aby to zrobić, zaznacz linie kodu, które chcesz zmienić, i naciśnij Ctrl + / na Windowsie (lub Cmd + / na macOS). Ta kombinacja klawiszy dodaje lub usuwa znacznik komentarza przy każdej zaznaczonej linii, czyniąc ten proces szybkim i efektywnym.