Jaki jest standardowy format docstring w Pythonie? [Zamknięte]

887

Widziałem kilka różnych stylów pisania dokumentów w Pythonie, czy istnieje styl oficjalny lub „uzgodniony”?

Noah McIlraith
źródło
6
python.org/dev/peps/pep-0008 jest cała sekcja poświęcona ciągom dokumentacji
Mechanical_meat
30
Myślę, że to pytanie nie było wystarczająco jasne, ponieważ PEP-257 i PEP-8 są ustalenia jedynie podstawę do docstrings, ale jak o epydoc, doxygen, sphinx? Czy ktoś ma jakieś statystyki, to jedna z nich zastąpi inne, w takich przypadkach zbyt wiele opcji może zaszkodzić.
sorin
1
@sorin, chciałbym również wiedzieć, jakie znaczniki, jeśli w ogóle, są najbardziej powszechne. Ale myślę, że odpowiedź jest taka, że ​​żaden z nich nie jest tak powszechny: ludzie wolą patrzeć bezpośrednio na źródło Pythona niż na html. Dlatego najbardziej przydatne jest zachowanie spójności, ale w sposób zoptymalizowany pod kątem czytelności dla człowieka i bez wyraźnego oznaczania.
poolie
3
PyCharm autouzupełnia się w dość interesujący sposób, co moim zdaniem jest fajną implementacją instrukcji potrzebnych do jego uruchomienia:def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""
Matteo Ferla
1
Która z tych odpowiedzi jest domyślnie działająca z analizatorem składni dokumentacji VS Code?
William Entriken,

Odpowiedzi:

1019

Formaty

Dokumenty w języku Python można pisać w kilku formatach, jak pokazały inne posty. Jednak domyślny format tekstowy Sphinx nie został wymieniony i jest oparty na reStructuredText (reST) . Informacje o głównych formatach można znaleźć w tym poście na blogu .

Zauważ, że reST jest zalecany przez PEP 287

Poniżej podano najczęściej używane formaty dokumentów.

- Epitext

Historycznie dominował styl podobny do javadoc , więc został on przyjęty jako podstawa dla Epydoc (w tak zwanym Epytextformacie) do generowania dokumentacji.

Przykład:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- reszta

Obecnie prawdopodobnie bardziej rozpowszechnionym formatem jest format reStructuredText (reST), który jest używany przez Sphinx do generowania dokumentacji. Uwaga: jest domyślnie używany w JetBrains PyCharm (wpisz potrójne cudzysłowy po zdefiniowaniu metody i wciśnij Enter). Jest również domyślnie używany jako format wyjściowy w płatności.

Przykład:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

Google ma własny format, który jest często używany. Może być również interpretowany przez Sphinx (tj. Przy użyciu wtyczki Napoleon ).

Przykład:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

Jeszcze więcej przykładów

- Numpydoc

Pamiętaj, że Numpy zaleca stosowanie własnego numpydoc opartego na formacie Google i używanego przez Sphinx.

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

Konwertowanie / generowanie

Możliwe jest użycie narzędzia, takiego jak Pyment, do automatycznego generowania dokumentów do projektu w języku Python, który nie został jeszcze udokumentowany, lub do konwersji istniejących dokumentów (z możliwością mieszania kilku formatów) z jednego formatu na inny.

Uwaga: przykłady pochodzą z dokumentacji płatności

daouzli
źródło
10
Mogę dodać, że reST jest domyślnie używany w JetBrains PyCharm, po prostu wpisz potrójne cudzysłowy po zdefiniowaniu metody i wciśnij Enter. jetbrains.com/pycharm/help/creating-documentation-comments.html
Felipe Almeida
12
Najbardziej wszechstronna odpowiedź, obejmująca historię i najlepsze praktyki. Teraz potrzebujemy tylko poczucia ruchu społeczności w kierunku nowego „najlepszego” formatu i dodatkowego wysiłku społeczności w kierunku tworzenia narzędzi migracji od wszystkich innych do nowego, abyśmy mogli rzeczywiście rozwinąć najlepsze praktyki.
BobHy
2
yo @daouzli, link w stylu Google to 404. Uważam, że ten jest poprawny. Możesz także dodać przykładowy styl Google Sphinx . Świetna odpowiedź btw. EDYCJA: Zredagowałem twoją odpowiedź samodzielnie.
podgląd
4
dobra odpowiedź. Odważę się powiedzieć, gdzie można zmienić domyślny format dokumentów w PyCharm (JetBrains): Ustawienia -> Narzędzia -> Zintegrowane narzędzia Python -> Format dokumentów. Powodzenia!
Jackssn
4
Dziwi mnie, że nikt nie skomentował pierwszej linii tekstu: obecnie jest ona ściśle mówiąc poprawna, ale wydaje mi się, że preferowanym sposobem jest umieszczenie jej w pierwszej linii tuż po potrójnych cudzysłowach. PEP 8 i PEP 257 robią to w prawie wszystkich swoich przykładach. PEP 287 robi to po swojemu, ale z mojego doświadczenia wynika, że ​​nie jest to tak powszechne.
Lapinot
323

Przewodnik po stylu Google zawiera doskonały przewodnik po stylu Python. Zawiera konwencje czytelnej składni dokumentów, która oferuje lepsze wskazówki niż PEP-257. Na przykład:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

Chciałbym to rozszerzyć, aby zawierało także informacje o typie w argumentach, jak opisano w tym samouczku dokumentacji Sphinx . Na przykład:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass
Nathan
źródło
37
Uważam, że styl „podpis w dokumentach” jest strasznie zbędny i gadatliwy. W przypadku Python 3+ adnotacje funkcji są o wiele czystszym sposobem na zrobienie tego. Jeszcze gorzej, jeśli używa pseudo-mocnych typów: Python jest znacznie lepszy w pisaniu kaczym.
Evpok
27
tak, ale przynajmniej daje wskazówkę, jakiej kaczki się spodziewamy, a większość deweloperów nie jest jeszcze w Pythonie 3
Anentropic
3
@Evpok osobiście, nie lubię adnotacji funkcyjnych. Aby użyć w nich klas, może być konieczne wykonanie niepotrzebnego importu, aby użyć w nich łańcuchów, może zabraknąć bardzo poziomego miejsca bardzo szybko je opisując. Jak dotąd nie widziałem sensu używania ich do niczego.
OdraEncoded
5
@Nathan, przewodnik po stylu Google zaleca komentarze, które mają charakter opisowy, a nie deklaratywny, np. „Pobiera wiersze z Bigtable” zamiast „Pobierz wiersze z Bigtable”. Zatem zmiana „Oblicz ...” na „Oblicz ...” sprawi, że twój przykład będzie bardziej spójny z resztą komentarza, tj. „Zwraca” i „Podwyżki”.
gwg
2
nit: Zgodnie ze stylem Google, używaj raczej formy opisowej niż rozkazującej, tj. „Oblicza ...” i „Dodaje ...”
sbeliakov
228

Konwencje docstring są w PEP-257 ze znacznie większą szczegółowością niż PEP-8.

Dokumenty wydają się jednak znacznie bardziej osobiste niż inne obszary kodu. Różne projekty będą miały swój własny standard.

Zazwyczaj zawsze dołączam dokumenty, ponieważ pokazują one, jak korzystać z funkcji i co robi bardzo szybko.

Wolę zachować spójność, niezależnie od długości łańcucha. Lubię kodować, kiedy wcięcia i odstępy są spójne. Oznacza to, że używam:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

Nad:

def sq(n):
    """Returns the square of n."""
    return n * n

I zwykle pomijam komentowanie pierwszego wiersza dłuższych dokumentów:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

To znaczy, uważam, że dokumenty, które zaczynają się tak, są niechlujne.

def sq(n):
    """Return the squared result. 
    ...
Tim McNamara
źródło
90
Zauważ, że PEP-8 wyraźnie mówi, że dokumenty należy zapisywać jako polecenia / instrukcje, a nie opisy, np. """Return the squared result"""raczej niż """Returns the squared result""". Chociaż osobiście piszę moje, jak tu są Tim, pomimo tego, co mówi PEP.
Cam Jackson
63
Nie zgadzam się również z tą radą (używając czasu rozkazującego), ponieważ zaczyna brzmieć niezręcznie w przypadku czegoś dłuższego niż jedno zdanie. Ponadto opisujesz funkcję, nie mówiąc czytelnikowi, co ma robić.
mk12
14
Uwaga: Specyfikacja raczej opisowych niż opisowych dokumentów faktycznie pojawia się w PEP-257 , a nie PEP-8. Pochodzę z tradycji Java, w której opisywałem funkcje, ale w końcu zacząłem używać czasu imperatywnego, kiedy mój paradygmat programistyczny przeszedł z obiektowego na proceduralny. A kiedy zacząłem używać pycco do generowania dokumentacji w stylu programowania piśmiennego, stało się bardzo jasne, dlaczego sugerowano czas rozkazujący. Powinieneś wybrać na podstawie swojego paradygmatu.
karan.dodia,
25
Imperatyw to gramatyczny nastrój . (Przepraszam.)
Denis Drescher
5
@ Mk12 Komunikaty Git commit powinny być również zapisywane jako polecenia zamiast opisów. Poza tym „ opisują ” zmianę kodu, „nie mówią czytelnikowi, co mają robić”. Myślę więc, że zapisywanie opisów jako poleceń jest zwyczajową konwencją.
onepiece
58

Jak zapewne nikt o tym nie wspomniał: możesz także użyć Numpy Docstring Standard . Jest szeroko stosowany w środowisku naukowym.

Rozszerzenie Sfinks Napolean do analizowania dokumentów w stylu Google (zalecane w odpowiedzi na @Nathan) obsługuje również dokumenty w stylu Numpy i dokonuje krótkiego porównania obu.

I na koniec podstawowy przykład, aby dać wyobrażenie o tym, jak to wygląda:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True
joris
źródło
2
Format NumPy IMHO zajmuje zbyt dużo miejsca w pionie, którego jest mało na monitorach szerokoekranowych (z wyjątkiem tego, że używasz jednego obróconego o 90 stopni, ale chyba większość ludzi tego nie robi). Tak więc IMHO Google Format to dobry wybór pod względem czytelności i funkcji.
Semanino,
3
Przypuszczam, że jest to nieco subiektywne. Kiedy masz bardziej złożony dokument (z różnymi sekcjami, przykładami itp., Więc i tak zajmuje dużo miejsca w pionie niezależnie od formatu), uważam, że format numpydoc jest łatwiejszy do odczytania / lepiej zorganizowany.
joris,
2
Osobiście uważam, że tak długi dokument jest lepiej umiejscowiony w dokumentacji, a nie w kodzie źródłowym, jeśli jest tak długi, że w końcu utrudniają czytelność modułu.
Jonathan Hartley,
12

PEP-8 jest oficjalnym standardem kodowania python. Zawiera sekcję dotyczącą dokumentów, która odnosi się do PEP-257 - kompletnej specyfikacji dokumentów.

bstpierre
źródło
8
Wzmianka o PEP-257 w kontekście „jak prawidłowo dokumentować parametry, zwracać wartości, zgłaszane wyjątki itp.” To Żart - nie mówi o nich ani słowa (choć przykład kodu pokazuje niektóre). IMHO Format Google to dobry wybór pod względem czytelności i funkcji.
Semanino,
9

To jest Python; wszystko idzie . Zastanów się, jak opublikować swoją dokumentację . Ciągi znaków są niewidoczne, z wyjątkiem czytników Twojego kodu źródłowego.

Ludzie naprawdę lubią przeglądać i przeszukiwać dokumentację w Internecie. Aby to osiągnąć, użyj narzędzia do dokumentacji Sphinx . Jest to de facto standard dokumentowania projektów w języku Python. Produkt jest piękny - spójrz na https://python-guide.readthedocs.org/en/latest/ . Witryna Read the Docs udostępni darmowe dokumenty.

Pułkownik Panika
źródło
22
Rutynowo używam ipythondo testowania biblioteki, a to sprawia, że ​​czytanie dokumentów jest bardzo proste - wszystko co muszę napisać to your_module.some_method_im_curious_about?dostaję każdy ładny wydruk, w tym dokumentację.
Thanatos,
8
Użytkownicy biblioteki lub interfejsu API lub piszący wtyczkę prawdopodobnie patrzą na kod i muszą go zrozumieć. Uważam, że komentarze są znacznie ważniejsze w Pythonie niż w Javie lub C #, ponieważ typy nie są deklarowane. Bardzo pomaga, jeśli komentarze dają z grubsza wyobrażenie o tym, jakie kaczki są przekazywane i zwracane. (W przeciwnym razie musisz przejść cały kod i zliczyć, że dany parametr musi ... być iterowalny tutaj ... obsługuje indeksowanie tam ... obsługuje odejmowanie numeryczne na końcu ... Aha! To w zasadzie int array. Komentarz by pomógł!)
Jon Coombs
Eh, nie. Naciągi nie są niewidoczne i to jest trochę o to chodzi. Zobaczysz docstring, jeśli uruchomisz helpfunkcję na udokumentowanej funkcji / metodzie / klasie (i możesz to zrobić, nawet jeśli masz dostęp tylko do skompilowanego modułu). Osobiście uważam, że należy o tym pamiętać przy wyborze konwencji docstringowej (tzn. Że zamierza się ją czytać taką, jaka jest).
skyking
7

Sugeruję użycie programu pep257 Python Vladimira Kelesheva do sprawdzania twoich dokumentów w PEP-257 i Numpy Docstring Standard do opisywania parametrów, zwrotów itp.

pep257 zgłosi rozbieżność, którą zrobisz ze standardu i nazywa się jak pylint i pep8.

Finn Årup Nielsen
źródło
Wzmianka o PEP-257 w kontekście „jak prawidłowo dokumentować parametry, zwracać wartości, zgłaszane wyjątki itp.” To Żart - nie mówi o nich ani słowa (choć przykład kodu pokazuje niektóre). Format NumPy IMHO zajmuje zbyt dużo miejsca w pionie, którego jest mało na monitorach szerokoekranowych (z wyjątkiem tego, że używasz jednego obróconego o 90 stopni, ale chyba większość ludzi tego nie robi). Tak więc IMHO Google Format to dobry wybór pod względem czytelności i funkcji.
Semanino,
1
@Semanino Wspominam o Numpy Docstring Standard w kontekście programu pep257, - nie PEP-257. Ten program nazywa się teraz pydocstyle. pydocstyle pozwala ci wykonać pewne kontrole numpydoc, np. pydocstyle --select=D4 tmp.pysprawdza szereg problemów z treścią dokumentów, w tym nazywanie sekcji.
Finn Årup Nielsen