Odpowiedź.

Historia pytania

W Pythonie od najwcześniejszych wersji zachęca się do dokumentowania kodu za pomocą docstring. Wraz z pojawieniem się Pythona 3.5 (PEP 484) wprowadzono adnotacje typów (type hints) w celu poprawy czytelności i wsparcia dla analizatorów typów (np. mypy, pyright itp.). Dzięki temu można łączyć dokumentację i typizację bezpośrednio w definicji funkcji i klas.

Problem

Bez adnotacji typów trudno szybko zrozumieć, z czym pracuje funkcja i czego od niej oczekiwać. Brak dobrych docstringów prowadzi do nieporozumień związanych z interfejsem i błędów w użyciu. Niewłaściwe użycie type hints lub docstringów utrudnia analizę statyczną i pogarsza wsparcie dla kodu.

Rozwiązanie

Używać wieloliniowych docstringów do dokumentowania przeznaczenia funkcji, parametrów i wyników, a także type hints do wyraźnego wskazywania typów argumentów i wartości zwracanej.

Przykład kodu:

def add_numbers(a: int, b: int) -> int:
    """
    Dodaje dwie liczby całkowite i zwraca wynik.

    :param a: Pierwsza suma, int
    :param b: Druga suma, int
    :return: Suma, int
    """
    return a + b

Kluczowe cechy:

Docstring jest przechowywany w doc i dostępny dla IDE, help(), generatorów dokumentacji
Adnotacje typów są dostępne przez annotations; nie wpływają na wykonanie kodu, tylko do analizy
Łączne zastosowanie ułatwia masową obsługę i onboardig nowych programistów

Pytania z pułapkami.

Czy adnotacje typów mogą wpływać na wykonanie programu?

Nie. Adnotacje typów (type hints) nie są sprawdzane przez interpreter Pythona podczas wykonywania i służą wyłącznie dla analizatorów i IDE oraz do automatycznej generacji dokumentacji. Nie prowadzą do błędów w czasie wykonywania i są zawsze opcjonalne.

Czy można używać adnotacji typów do ograniczenia wartości parametru?

Nie. Wskazanie typu, np. x: int, nie zabrania przekazania wartości innego typu w praktyce. W tym celu można stosować sprawdzenia czasu wykonania (assert/isinstance), ale nie type hints — nie są one automatycznie weryfikowane.

Czy można używać komentarzy # type: ... zamiast adnotacji? Po co to czasami potrzebne?

Tak, to jest dozwolone, jeśli potrzebna jest zgodność z Pythonem 2 lub ze starszymi bazami kodu. Na przykład:

def foo(x, y):     # type: (int, str) -> bool
    pass

To rozumieją mypy i podobne narzędzia na równi z nowoczesną składnią, ale w nowych projektach lepiej używać standardowych adnotacji.

Typowe błędy i antywzorce

Brak docstringów lub pusty docstring w publicznych funkcjach i klasach
Niewłaściwe wskazanie typów — na przykład, List zamiast list lub literówki w typach (szczególnie złożonych kolekcjach)
Użycie type hints bez aktualizacji dokumentacji i odwrotnie

Przykład z życia

Negatywny przypadek

W dużym projekcie funkcje nie mają w ogóle docstringów ani type hints — programista spędza dużo czasu na studiowaniu i debugowaniu, często myli się co do typów i przeznaczenia danych wejściowych.

Zalety:

Szybkie pisanie kodu na początku

Wady:

Duże trudności w utrzymaniu, onboarding nowych pracowników jest znacznie opóźniony
Błędy trudno wychwycić, jeśli parametry mają pomieszane typy

Pozytywny przypadek

Wszystkie publiczne funkcje zawierają rozwinięte docstringi i poprawne type hints, co pozwala IDE i analizatorom szybko znajdować błędy typów i automatycznie generować dokumentację dla API.