Komentarze w Pythonie: jednoliniowe, wieloliniowe i docstringi

Komentarze są dla ludzi

Python ignoruje komentarze. Na tym polega cała sztuczka. Wszystko, co oznaczysz jako komentarz, jest niewidoczne dla interpretera: istnieje wyłącznie dla osoby czytającej kod, czyli zwykle dla ciebie za pół roku, gdy zaczniesz się zastanawiać, o co wtedy chodziło.

Mimo to komentarz, który tylko powtarza to, co kod oczywiście robi, nie jest wart pisania. Najlepsze komentarze wyjaśniają dlaczego: ograniczenie, obejście, decyzję, której nie widać w samym kodzie. Kod już mówi, co się dzieje.

Komentarze jednoliniowe z #

Podstawowa forma to #, a po nim twoja notatka:

# Calculate the tax portion of the total.
total = 100
tax = total * 0.08
print(tax)

Krótki komentarz możesz też dopisać na końcu linii. Zgodnie z konwencją zostaw przed # co najmniej dwie spacje:

refresh_interval = 300  # seconds; keep in sync with the dashboard config
print(refresh_interval)

Python traktuje # w dowolnym miejscu poza napisem jako początek komentarza do końca linii. Ważne jest to "poza napisem": # w cudzysłowie to zwykły znak.

url = "https://example.com/#section-2"  # the real comment starts here
print(url)

#section-2 w napisie jest częścią adresu URL. Python przechodzi w tryb "komentarza" dopiero przy # po zamknięciu napisu.

Zakomentowanie wielu linii

Python nie ma komentarza blokowego /* */. Żeby pominąć kilka linii, postaw # na początku każdej:

# This is a block comment.
# It spans several lines.
# Each line starts with its own #.
print("only this line actually runs")

Prawie nigdy nie wpisuje się tych # ręcznie. Każdy przyzwoity edytor ma skrót "przełącz komentarz linii", który dodaje albo usuwa # na każdej zaznaczonej linii:

• VS Code: Cmd + / (macOS) albo Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / albo Ctrl + /
• Vim: zależy od wtyczek; vim-commentary przypisuje gcc do pojedynczej linii i gc do zaznaczenia.

Naucz się raz skrótu w swoim edytorze, a "zakomentowanie tego bloku, żeby coś wypróbować" stanie się operacją na jedno naciśnięcie klawisza.

Sztuczka z potrójnym cudzysłowem (i dlaczego to nie jest prawdziwy komentarz)

Czasem zobaczysz taki kod:

"""
This block looks like a comment
but it's actually a string literal
that nothing uses.
"""
print("hi")

Technicznie to wyrażenie z napisem, które zostaje odrzucone. Python je parsuje, oblicza i wyrzuca wynik. Zachowuje się jak komentarz, ale nim nie jest. Stylistycznie to dobry pomysł tylko w jednym konkretnym miejscu: jako docstring.

Docstringi: jedyne miejsce na potrójny cudzysłów

Docstring to napis w potrójnym cudzysłowie umieszczony jako pierwsza instrukcja funkcji, klasy albo modułu. Python rozpoznaje go jako dokumentację i udostępnia w trakcie działania przez funkcję help() i atrybut __doc__:

def discount(price, percent):
    """Return the final price after applying a percentage discount.

    price is a number; percent is between 0 and 100.
    """
    return price * (1 - percent / 100)

print(discount(50, 20))
help(discount)

Docstringi są przydatne z dwóch powodów:

1. Narzędzia takie jak IDE, help() i generatory dokumentacji czytają je automatycznie. Komentarz nad funkcją nic takiego nie daje.
2. Opisują funkcję w miejscu wywołania: gdy ktoś najedzie kursorem na discount(...) w edytorze, docstring pojawia się jako podpowiedź.

Istnieje konwencja (PEP 257) dotycząca zawartości docstringa: jednozdaniowe podsumowanie w pierwszej linii, pusta linia, a potem dłuższy opis, jeśli jest potrzebny. Pierwszego dnia nie przejmuj się dokładnym formatem: zwykłe jedno zdanie i tak jest dużo lepsze niż brak docstringa.

Co naprawdę mówią dobre komentarze

Kilka wskazówek, które oszczędzą wielu zmartwień w przyszłości:

• Opisuj raczej dlaczego niż co. # Loop over the users to szum; # Retry on 503 - Redis sometimes dies mid-deploy to złoto.
• Aktualizuj komentarze, gdy zmieniasz kod. Błędny komentarz jest gorszy niż żaden. Nieaktualne komentarze aktywnie wprowadzają w błąd przyszłych czytelników.
• Nie zostawiaj zakomentowanego kodu. Jeśli go nie potrzebujesz, usuń go. System kontroli wersji pamięta. Plik usiany zakomentowanymi blokami szybko traci wiarygodność.
• Pomijaj oczywistości. x = x + 1 # increment x niczego nie wnosi.

Podsumowanie

Komentarze nic nie kosztują i łatwo je pominąć. Sięgaj po nie, gdy zostawiasz notatkę, za którą czytelnik ci podziękuje: subtelny powód, dla którego coś działa, link do zgłoszenia, ostrzeżenie o przypadku brzegowym. Używaj docstringów, gdy definiujesz funkcję albo klasę. Poza tym niech mówią za ciebie jasne nazwy i małe funkcje.

Masz już wszystko, czego potrzebujesz, żeby czytać i pisać plik Pythona. W następnym rozdziale język naprawdę zaczyna działać: zmienne, typy danych i wartości, które Python potrafi przechowywać.