Komentarze w Pythonie

1. Jak pisać komentarze

W Pythonie, tak jak w wielu innych językach programowania, można pisać komentarze w kodzie.

Komentarze to po prostu tekst dla innych programistów: interpreter Pythona ich nie przetwarza i nie wykonuje zawartego w nich kodu. Komentarze pomagają programistom oraz innym członkom projektu zrozumieć kod, co jest szczególnie przydatne przy pracy zespołowej i długoterminowym utrzymaniu programów. W Pythonie istnieje kilka sposobów dodawania komentarzy do kodu.

Komentarze jednoliniowe:

Rozpoczynają się od symbolu #. Wszystko, co znajduje się po # w tej samej linii, jest ignorowane przez interpreter Pythona. Ten typ komentarzy jest zwykle używany do krótkich uwag lub wyjaśnień dotyczących konkretnej linii kodu. Przykład:

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

Komentarze wieloliniowe:

W Pythonie oficjalnie nie istnieje specjalna składnia dla komentarzy wieloliniowych, ale można je stworzyć za pomocą kilku komentarzy jednoliniowych lub używając potrójnych cudzysłowów, chociaż te ostatnie są tak naprawdę literowymi ciągami znaków, które nie są wykonywane jako kod. Przykład:

# To jest przykład komentarza wieloliniowego
# Każda linia zaczyna się symbolem `#`

albo:

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

Przydatne! Literowy ciąg to mały kawałek danych zapisanych bezpośrednio w kodzie: liczba, ciąg znaków itp.

2. Dlaczego pisać komentarze

Korzystanie z komentarzy w kodzie zwiększa jego czytelność, ułatwia utrzymanie i aktualizacje, a także sprzyja bardziej efektywnej współpracy w zespołach. Komentarze powinny być krótkie, ale informacyjne i aktualne, aby służyć jako przydatna dokumentacja kodu i nie zaśmiecać go nadmierną ilością informacji.

Docstrings:

To wieloliniowe ciągi znaków, które zazwyczaj znajdują się na początku modułów, klas, metod i funkcji, opisując ich przeznaczenie. Są one zamknięte w trzy pary podwójnych cudzysłowów i 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 deweloperzy czasami dodają do swojego kodu komentarze, które nie tylko służą za wyjaśnienia, ale także wywołują uśmiech. Oto kilka przykładów zabawnych komentarzy, które można znaleźć w kodzie:

Przykład 1:

# Wyjaśniłbym, co tutaj się dzieje, ale nawet już sam tego nie rozumiem.

Przykład 2:

# Jeśli to nie działa, to ktoś inny jest winny.

Przykład 3:

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

Przykład 4:

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

Przykład 5:

# Liczba godzin zmarnowanych tutaj = 42.

Takie komentarze mogą dodać lekkości i humoru do procesu tworzenia, sprawiając, że baza kodu staje się mniej monotonna. Przypominają również, że programowanie to proces twórczy i ludzki.

5.3 Szybkie komentowanie kodu

W PyCharm IDE można szybko zakomentować lub odkomentować kod, używając skrótów klawiszowych. Aby to zrobić, zaznacz linie kodu, które chcesz zakomentować lub odkomentować, i naciśnij Ctrl + / w Windows (lub Cmd + / w macOS). Ta kombinacja klawiszy wstawia lub usuwa symbol komentarza na każdej zaznaczonej linii, co sprawia, że proces ten jest szybki i efektywny.