Docstringi w Pythonie to łańcuchy dokumentacyjne, które są używane do opisania działania modułów, funkcji, klas i metod. Są to wieloliniowe komentarze, które pomagają innym programistom, a także przyszłemu “ja”, zrozumieć, co dany fragment kodu robi, jak go używać i jakie wartości oczekuje lub zwraca. Docstringi są bardzo ważne w profesjonalnym programowaniu, ponieważ przyczyniają się do lepszej czytelności i utrzymywalności kodu.
Przykład kodu z docstringami
Poniżej znajduje się przykład funkcji w Pythonie, która wykorzystuje docstring do opisania swojego działania:
def add_numbers(a, b):
"""
Dodaje dwie liczby i zwraca ich sumę.
Parametry:
a (int): Pierwsza liczba do dodania.
b (int): Druga liczba do dodania.
Zwraca:
int: Suma dwóch liczb.
"""
return a + b
W powyższym przykładzie, docstring znajdujący się bezpośrednio pod definicją funkcji add_numbers szczegółowo opisuje, co funkcja robi, jakie parametry przyjmuje (wraz z ich typami) oraz co funkcja zwraca. Jest to bardzo użyteczne, szczególnie w dużych projektach, gdzie różne części kodu są ze sobą ściśle powiązane.
Jak korzystać z docstringów?
Docstringi umieszcza się bezpośrednio pod definicją modułu, klasy, metody lub funkcji. Python wykorzystuje trzy cudzysłowy (zarówno pojedyncze ''' jak i podwójne """) do zdefiniowania docstringów, co pozwala na umieszczenie w nich wieloliniowego tekstu.
Oto kolejny przykład, tym razem z klasą używającą docstringów:
class Calculator:
"""
Klasa Calculator służy do wykonywania prostych operacji matematycznych.
Metody:
add(a, b) - zwraca sumę dwóch liczb.
subtract(a, b) - zwraca różnicę dwóch liczb.
"""
def add(self, a, b):
"""
Dodaje dwie liczby i zwraca ich sumę.
Parametry:
a (int): Pierwsza liczba.
b (int): Druga liczba.
Zwraca:
int: Suma a i b.
"""
return a + b
def subtract(self, a, b):
"""
Odejmuje drugą liczbę od pierwszej i zwraca wynik.
Parametry:
a (int): Liczba, od której odejmujemy.
b (int): Liczba, którą odejmujemy.
Zwraca:
int: Różnica a i b.
"""
return a - b
Dlaczego warto używać docstringów?
- Dokumentacja w miejscu użycia: Docstringi są integralną częścią kodu, co oznacza, że dokumentacja jest zawsze tam, gdzie jest potrzebna.
- Wsparcie narzędzi: Narzędzia takie jak Sphinx mogą automatycznie generować dokumentację na podstawie docstringów, co znacznie ułatwia utrzymanie aktualnej dokumentacji projektu.
- Interaktywna pomoc: Używając interpretera Pythona, możesz łatwo uzyskać dostęp do docstringów za pomocą funkcji
help()lub atrybutu__doc__, co jest niezwykle przydatne podczas pracy w interaktywnym środowisku.
Podsumowanie
Docstringi w Pythonie to potężne narzędzie do dokumentowania kodu. Umożliwiają one tworzenie przejrzystych i łatwych do zrozumienia opisów modułów, klas,
Jeżeli chcesz przyśpieszyć swoją naukę tworzenia stron chciałbym polecić mój kurs video Python w którym nauczysz się tego języka od podstaw do zaawansowanych jego aspektów.