Dobry kod zawiera komentarze, które pomagają go zrozumieć, a dokumenty mogą odgrywać w tym ważną rolę.

Bez odpowiedniej dokumentacji zrozumienie, konserwacja i debugowanie kodu może być trudne. W Pythonie możesz użyć docstringów, aby podać zwięzłe opisy i przykłady działania kodu.

Co to są dokumenty?

Docstringi to ciągi znaków, które możesz dodać do kodu Pythona, aby wyjaśnić, co on robi i jak go używać. Fragment kodu może być a Funkcja Pythona, moduł lub klasa.

Dokumenty wyglądają bardzo podobnie do standardowych komentarzy Pythona, ale mają pewne różnice. Komentarze w języku Python dostarczają programistom dodatkowych informacji na temat wewnętrznego działania kodu, takich jak szczegóły implementacji lub zastrzeżenia, o których należy pamiętać podczas rozszerzania kodu.

Z drugiej strony, docstringi dostarczają głównie informacji użytkownikom kodu, którzy niekoniecznie muszą znać szczegóły jego implementacji, ale muszą zrozumieć, co on robi i jak go używać.

Jak pisać dokumenty

Zazwyczaj dołączasz docstringi na początku bloku kodu, który chcesz udokumentować. Musisz je ująć w potrójne cudzysłowy (). Możesz pisać jednowierszowe docstringi lub wielowierszowe docstringi.

instagram viewer

Docstringi jednowierszowe są odpowiednie dla prostego kodu, który nie wymaga dużej ilości dokumentacji.

Poniżej znajduje się przykład funkcji zwanej mnożeniem. Docstring wyjaśnia, że ​​funkcja mnożenia przyjmuje dwie liczby, mnoży je i zwraca wynik.

pokzwielokrotniać(a, b):
Mnoży dwie liczby i zwraca wynik
powrót a * b

W przypadku bardziej złożonego kodu, który wymaga szczegółowej dokumentacji, używaj wielowierszowych ciągów dokumentów.

Rozważ następującą klasę samochodów:

klasaSamochód:

 A klasareprezentującyAsamochódobiekt.
 Atrybuty:
 przebieg (float): Aktualny przebieg samochodu.


 Metody:
 drive (mile): Prowadzi samochód Do określoną liczbę mil.


pok__w tym__(samodzielnie, przebieg):
 własny.przebieg = przebieg


pokprowadzić(ja, mile):

 Prowadzi samochód Do określoną liczbę mil.


 Argumenty:
 mile (float): Liczba mil do przejechania.
 Zwroty:
Nic

 własny.przebieg += mile

Dokumentacja dla powyższej klasy opisuje, co klasa reprezentuje, jej atrybuty i metody. Tymczasem dokumenty metody drive dostarczają informacji o tym, co robi metoda, jakich argumentów oczekuje i co zwraca.

Ułatwia to każdemu, kto pracuje z tą klasą, zrozumienie, jak z niej korzystać. Inne korzyści płynące z używania docstringów to:

  • Łatwość utrzymania kodu: dostarczając jasny opis działania kodu, dokumenty pomagają programistom modyfikować i aktualizować kod bez wprowadzania błędów.
  • Łatwiejsza współpraca: kiedy kilku programistów współpracuje nad tą samą bazą kodu — na przykład z Narzędzie udostępniania na żywo programu Visual Studio—docstrings umożliwiają programistom spójną dokumentację kodu, tak aby każdy w zespole mógł go zrozumieć.
  • Poprawiona czytelność kodu: Docstrings zapewniają ogólne podsumowanie tego, co kod robi i na co pozwala każdemu, kto czyta kod, aby szybko zrozumieć jego cel bez przeglądania całego kodu blok.

Formaty dokumentów

Dobry ciąg dokumentów powinien opisywać, co robi fragment kodu, jakich argumentów oczekuje i, jeśli to konieczne, szczegóły implementacji. Powinien w szczególności obejmować wszelkie skrajne przypadki, o których każdy korzystający z kodu powinien wiedzieć.

Podstawowy format docstring ma następujące sekcje:

  • Wiersz podsumowania: jednowierszowe podsumowanie tego, co robi kod.
  • Argumenty: Informacje o argumentach oczekiwanych przez funkcję, w tym ich typy danych.
  • Wartość zwracana: Informacja o wartości zwracanej przez funkcję wraz z jej typem danych.
  • Podbicia (opcjonalnie): Informacje o wszelkich wyjątkach, które funkcja może zgłosić.

Jest to tylko podstawowy format, ponieważ istnieją inne formaty, na których można oprzeć swoje dokumenty. Najpopularniejsze z nich to Epytext, reStructuredText (znany również jako reST), NumPy i Google docstrings. Każdy z tych formatów ma swoją własną składnię, jak pokazano w poniższych przykładach:

epitekst

Dokumentacja zgodna z formatem Epytext:

pokzwielokrotniać(a, b):

 Pomnóż przez siebie dwie liczby.
 @param a: Pierwsza liczba do pomnożenia.
 @type a: int
 @param b: Druga liczba do pomnożenia.
 @type b: int
 @return: iloczyn dwóch liczb.
 @rtype: int

powrót a * b

ReStructuredText (reST)

Dokumentacja zgodna z formatem reST:

pokzwielokrotniać(a, b):

 Pomnóż przez siebie dwie liczby.
 :param a: Pierwsza liczba do pomnożenia.
 :wpisz a: int
 :param b: Druga liczba do pomnożenia.
 :typ b: wewn
 :powrót: iloczyn dwóch liczb.
 :rtype: int

powrót a * b

LiczbaPy

Dokumentacja zgodna z formatem NumPy:

pokzwielokrotniać(a, b):

 Pomnóż przez siebie dwie liczby.
 Parametry

 a: int
 Pierwsza liczba do pomnożenia.
 b: wew
 Druga liczba do pomnożenia.
 Zwroty

 int
 Iloczyn dwóch liczb.

powrót a * b

Google

Dokumentacja zgodna z formatem Google:

pokzwielokrotniać(a, b):

 Pomnóż przez siebie dwie liczby.
 Argumenty:
 a (int): Pierwsza liczba do pomnożenia.
 b (int): Druga liczba do pomnożenia.
 Zwroty:
 int: iloczyn dwóch liczb.

powrót a * b

Chociaż wszystkie cztery formaty docstring dostarczają przydatnej dokumentacji funkcji mnożenia, formaty NumPy i Google są łatwiejsze do odczytania niż formaty Epytext i reST.

Jak dołączyć testy do Docstrings

Możesz dołączyć przykłady testowania do swoich dokumentów za pomocą modułu doctest. Moduł doctest przeszukuje dokumentację w poszukiwaniu tekstu, który wygląda jak interaktywne sesje Pythona, a następnie wykonuje je, aby sprawdzić, czy działają tak, jak powinny.

Aby użyć doctestów, dołącz przykładowe dane wejściowe i oczekiwane wyniki do dokumentu. Poniżej znajduje się przykład, jak można to zrobić:

pokzwielokrotniać(a, b):

 Pomnóż przez siebie dwie liczby.
 Parametry

 a: int
 Pierwsza liczba do pomnożenia.
 b: wew
 Druga liczba do pomnożenia.


 Zwroty

 int
 Iloczyn dwóch liczb.
 Przykłady

 >>> pomnóż(2, 3)
6
 >>> pomnóż(0, 10)
0
 >>> pomnóż(-1, 5)
-5

powrót a * b

The Przykłady sekcja zawiera trzy wywołania funkcji z różnymi argumentami i określa oczekiwane dane wyjściowe dla każdego z nich. Po uruchomieniu modułu doctest, jak pokazano poniżej, wykona on przykłady i porówna rzeczywisty wynik z oczekiwanym wynikiem.

python -m doctest mnoż.py

Jeśli występują różnice, moduł doctest zgłasza je jako awarie. Używanie doctestów z takimi dokumentami pomaga zweryfikować, czy kod działa zgodnie z oczekiwaniami. Należy pamiętać, że doctesty nie zastępują bardziej kompleksowych testy jednostkowe i testy integracyjne dla twojego kodu Pythona.

Jak wygenerować dokumentację z Docstrings

Poznałeś podstawy używania docstringów do dokumentowania kodu w Pythonie i znasz znaczenie wysokiej jakości dokumentacji. Aby podnieść poprzeczkę, możesz chcieć wygenerować dokumentację dla swoich modułów i funkcji z ich odpowiednich dokumentów.

Jednym z najpopularniejszych generatorów dokumentacji, z których można korzystać, jest Sphinx. Domyślnie obsługuje format docstring reST, ale można go skonfigurować do pracy z formatem Google lub NumPy.