Komentarz

🐍 Komentarze w Pythonie — małe notatki o wielkim znaczeniu

Pisząc kod w Pythonie (i w każdym innym języku programowania), prędzej czy później trafimy na coś, co wydaje się oczywiste... do momentu, gdy po miesiącu wrócimy do projektu i nie mamy pojęcia, dlaczego dany fragment wygląda tak, a nie inaczej.
Właśnie wtedy z pomocą przychodzą komentarze.

💬 Co to jest komentarz?

Komentarz to część kodu, którą interpreter Pythona ignoruje — nie wpływa na działanie programu.
Służy wyłącznie dla ludzi: do wyjaśniania, dokumentowania i organizowania kodu.

W Pythonie komentarze mogą być:

• jednoliniowe

• wieloliniowe (blokowe)

• docstringi (specjalny typ komentarza/dokumentacji)

---

📝 Komentarze jednoliniowe

Najczęściej używane.
Zaczynają się od znaku # i kończą wraz z końcem linii.

# To jest komentarz w Pythonie
print("Hello, world!")  # Ten komentarz objaśnia, co robi ten wiersz

To prosty sposób, by opisać fragment kodu lub zaznaczyć coś do poprawy:

# TODO: dodać walidację danych wejściowych

---

📄 Komentarze wieloliniowe

Python nie ma dedykowanej składni dla komentarzy wieloliniowych, ale można użyć kilku # z rzędu:

# Ten fragment kodu oblicza średnią arytmetyczną
# z listy liczb. W przyszłości warto dodać obsługę błędów.

Czasem początkujący używają potrójnych cudzysłowów """ ... """, jednak to nie są komentarze, tylko łańcuchy tekstowe (stringi), które po prostu nie są przypisane do zmiennej:

"""
To wygląda jak komentarz,
ale technicznie jest to string,
którego Python po prostu nie używa.
"""

---

📚 Docstringi — dokumentacja funkcji i klas

Docstring (skrót od documentation string) to specjalny rodzaj komentarza, który służy do dokumentowania funkcji, klas i modułów.
Umieszcza się go bezpośrednio po definicji funkcji, klasy lub modułu, w potrójnych cudzysłowach (""" ... """).

def greet(name):
    """
    Funkcja wyświetla powitanie użytkownika.
    
    Parametry:
        name (str): Imię użytkownika
    
    Zwraca:
        None
    """
    print(f"Cześć, {name}!")

Dzięki docstringom można potem uzyskać dokumentację z poziomu Pythona:

help(greet)

---

⚙️ Dobre praktyki pisania komentarzy

✅ Komentuj z umiarem.
Nie opisuj oczywistości:

x = x + 1  # zwiększ x o 1  ❌ (niepotrzebne)

✅ Wyjaśniaj dlaczego, nie co robi kod.
Kod często mówi sam za siebie, ale motywacja autora już nie.

✅ Utrzymuj komentarze w aktualności.
Stary, błędny komentarz jest gorszy niż brak komentarza.

✅ Używaj TODO, FIXME, NOTE.
To ułatwia wyszukiwanie ważnych miejsc w kodzie:

# TODO: dodać logowanie błędów
# FIXME: naprawić dzielenie przez zero
# NOTE: w Pythonie 3.10 zmieniono sposób obsługi wyjątków

---

🧭 Podsumowanie

Komentarze to nie tylko ozdoba kodu, ale narzędzie komunikacji — między Tobą a przyszłym Tobą, między Tobą a zespołem.
Dobrze napisane komentarze czynią kod bardziej zrozumiałym, utrzymywalnym i przyjaznym.

Jak mówi stare powiedzenie programistów:

„Kod jest dla komputerów, komentarze są dla ludzi.”

---

Czy chcesz, żebym dostosował ten wpis do konkretnego stylu — np. bardziej technicznego, dla początkujących, albo z przykładami z projektu open-source?