Zanurkuj w Pythonie/Dokumentowanie funkcji

Z Wikibooks, biblioteki wolnych podręczników.

[edytuj] Dokumentowanie funkcji

Funkcje można dokumentować wstawiając notkę dokumentacyjną (ang. doc string).

def buildConnectionString(params):
    u"""Tworzy łańcuch znaków na podstawie słownika parametrów.
    
    Zwraca łańcuch znaków.
    """
    return ";".join(["%s=%s" % (k, v) for k, v in params.items()])
 

Trzy następujące po sobie cudzysłowy wykorzystuje się do tworzenia ciągu znaków, który może zajmować wiele linii. Wszystko co się znajduje pomiędzy nimi tworzy pojedynczy łańcuch znaków; dotyczy to także znaków powrotu karetki i cudzysłowu. Potrójne cudzysłowy możemy używać wszędzie, ale najczęściej wykorzystuje się je do tworzenia notek dokumentacyjnych.

Za pomocą potrójnych cudzysłowów ("""...""") możemy w łatwy sposób zdefiniować łańcuch znaków zawierający pojedyncze jak i podwójne cudzysłowy, podobnie jak w przypadku qq/../ w Perlu.

Dzięki przedrostkowi u Python zapamięta ten łańcuch znaków w taki sposób, że będzie potrafił poprawnie zinterpretować polskie litery. Więcej szczegółów na ten temat dowiemy się w dalszej części tej książki.

W powyższym przykładzie wszystko pomiędzy potrójnymi cudzysłowami jest notką dokumentacyjną funkcji, czyli opisem do czego dana funkcja służy i jak ją używać. Notka dokumentacyjna, o ile istnieje, musi znaleźć się pierwsza w definicji funkcji (czyli zaraz po dwukropku). Python nie wymaga, aby funkcja posiadała notkę dokumentacyjną, lecz powinniśmy ją zawsze tworzyć. Ułatwia ona nam, a także innym, zorientować się w programie. Warto zaznaczyć, że notka dokumentacyjna jest dostępna jako atrybut funkcji nawet w trakcie wykonywania programu.

Wiele pythonowych IDE wykorzystuje notki dokumentacyjne do "inteligentnej pomocy", czyli wyświetlania informacji (pobranej z notki dokumentacyjnej) o funkcji po wpisaniu jej nazwy. Może to stanowić dla nas nieocenioną pomoc, oczywiście pod warunkiem, że notki dokumentacyjne zostały przez nas zdefiniowane...

[edytuj] Materiały dodatkowe

Materiały co prawda w języku angielskim, ale na pewno warto je chociaż przejrzeć:

• PEP 257, na temat konwencji notek dokumentacyjnych,
• Python Style Guide, o tym, jak napisać dobrą notkę dokumentacyjną,