Python Language
Komentarze i dokumentacja

Składnia

• # To jest komentarz jednowierszowy
• print („”) # To jest komentarz wbudowany
• „” „
  To jest
  komentarz wielowierszowy
  „” „

Uwagi

Komentarze jednowierszowe, wbudowane i wielowierszowe

Komentarze służą do wyjaśnienia kodu, gdy sam podstawowy kod nie jest jasny.

Python ignoruje komentarze, więc nie będzie tam wykonywać kodu ani zgłaszać błędów składniowych zwykłych angielskich zdań.

Komentarze jednowierszowe rozpoczynają się od znaku krzyżyka ( # ) i kończą do końca linii.

• Komentarz jednowierszowy:

# This is a single line comment in Python

• Komentarz wewnętrzny:

print("Hello World")  # This line prints "Hello World"

• Komentarze obejmujące wiele wierszy mają """ lub ''' na obu końcach. Jest to to samo, co ciąg multilinii, ale można ich używać jako komentarzy:

"""
This type of comment spans multiple lines.
These are mostly used for documentation of functions, classes and modules.
"""

Programowy dostęp do dokumentów

Dokumenty są - w przeciwieństwie do zwykłych komentarzy - przechowywane jako atrybut funkcji, którą dokumentują, co oznacza, że można uzyskać do nich dostęp programowo.

Przykładowa funkcja

def func():
    """This is a function that does nothing at all"""
    return

Dostęp do __doc__ można uzyskać za pomocą atrybutu __doc__ :

print(func.__doc__)

Jest to funkcja, która w ogóle nic nie robi

help(func)

Pomoc na temat funkcji func w module __main__ :

func()

Jest to funkcja, która w ogóle nic nie robi

Kolejna przykładowa funkcja

function.__doc__ to tylko ciąg znaków jako ciąg znaków, podczas gdy funkcja help dostarcza ogólnych informacji o funkcji, w tym ciągu znaków. Oto bardziej pomocny przykład:

def greet(name, greeting="Hello"):
    """Print a greeting to the user `name`

    Optional parameter `greeting` can change what they're greeted with."""
    
    print("{} {}".format(greeting, name))

help(greet)

Pomoc na greet funkcji w module __main__ :

greet(name, greeting='Hello')

Wydrukuj powitanie do name użytkownika
Opcjonalne greeting parametru może zmienić powitanie.

Zalety dokumentów w porównaniu do zwykłych komentarzy

Samo umieszczanie w dokumencie funkcji docstring lub regularnego komentarza nie jest tak pomocne.

def greet(name, greeting="Hello"):
    # Print a greeting to the user `name`
    # Optional parameter `greeting` can change what they're greeted with.
    
    print("{} {}".format(greeting, name))

print(greet.__doc__)

Żaden

help(greet)

Pomoc na powitanie funkcji w module głównym :

greet(name, greeting='Hello')

Pisz dokumentację za pomocą dokumentów

Docstring to wieloliniowy komentarz używany do dokumentowania modułów, klas, funkcji i metod. Musi to być pierwsza instrukcja opisywanego komponentu.

def hello(name):
    """Greet someone.

    Print a greeting ("Hello") for the person with the given name.
    """

    print("Hello "+name)

class Greeter:
    """An object used to greet people.

    It contains multiple greeting functions for several languages
    and times of the  day.
    """

Do wartości docstring można uzyskać dostęp w programie i - na przykład - jest on używany przez polecenie help .

Konwencje składniowe

PEP 257

PEP 257 definiuje standard składni komentarzy do dokumentów. Zasadniczo pozwala na dwa typy:

• Dokumenty jednowierszowe:

Zgodnie z PEP 257 powinny być używane z krótkimi i prostymi funkcjami. Wszystko jest umieszczone w jednej linii, np .:

def hello():
    """Say hello to your friends."""
    print("Hello my friends!")

Dokument powinien kończyć się kropką, czasownik powinien być w formie rozkazującej.

• Dokumenty wieloliniowe:

W przypadku dłuższych, bardziej złożonych funkcji, modułów lub klas należy używać wieloliniowego docstring.

def hello(name, language="en"):
    """Say hello to a person.

    Arguments:
    name: the name of the person
    language: the language in which the person should be greeted
    """

    print(greeting[language]+" "+name)

Zaczynają się od krótkiego podsumowania (odpowiadającego treści jednowierszowego dokumentu), które może znajdować się w tym samym wierszu co znaki cudzysłowu lub w następnym wierszu, podając dodatkowe szczegóły i parametry listy oraz zwracane wartości.

Uwaga PEP 257 określa, jakie informacje należy podać w dokumencie, nie określa, w jakim formacie należy je podać. To był powód dla innych stron i narzędzi do analizowania dokumentacji do określenia własnych standardów dla dokumentacji, z których niektóre są wymienione poniżej i w tym pytaniu .

Sfinks

Sphinx to narzędzie do generowania dokumentacji opartej na HTML dla projektów Python na podstawie dokumentów. Jego językiem znaczników jest reStructuredText . Definiują własne standardy dokumentacji, pythonhosted.org udostępnia bardzo dobry ich opis . Format Sphinx jest na przykład używany przez pyCharm IDE .

Funkcja powinna być udokumentowana w ten sposób przy użyciu formatu Sphinx / reStructuredText:

def hello(name, language="en"):
    """Say hello to a person.

    :param name: the name of the person
    :type name: str
    :param language: the language in which the person should be greeted
    :type language: str
    :return: a number
    :rtype: int
    """

    print(greeting[language]+" "+name)
    return 4

Przewodnik po stylu Python Google

Google opublikował Przewodnik po stylu Python, który definiuje konwencje kodowania dla Pythona, w tym komentarze do dokumentacji. W porównaniu do Sphinx / reST wiele osób twierdzi, że dokumentacja zgodna z wytycznymi Google jest bardziej czytelna dla człowieka.

Wspomniana wyżej strona pythonhosted.org zawiera również przykłady dobrej dokumentacji zgodnie z Przewodnikiem po stylu Google.

Za pomocą wtyczki Napoleon Sphinx może również analizować dokumentację w formacie zgodnym z Przewodnikiem po stylu Google.

Funkcja może być udokumentowana w następujący sposób przy użyciu formatu Przewodnika po stylu Google:

def hello(name, language="en"):
    """Say hello to a person.

    Args:
        name: the name of the person as string
        language: the language code string

    Returns:
        A number.
    """

    print(greeting[language]+" "+name)
    return 4