Python Language
Kommentare und Dokumentation

Syntax

• # Dies ist ein einzeiliger Kommentar
• print ("") # Dies ist ein Inline-Kommentar
• "" "
  Das ist
  ein mehrzeiliger Kommentar
  "" "

Bemerkungen

Einzeilige, inline und mehrzeilige Kommentare

Kommentare werden zum Erklären von Code verwendet, wenn der Basiscode selbst nicht klar ist.

Python ignoriert Kommentare und führt daher keinen Code aus oder führt zu Syntaxfehlern für einfache englische Sätze.

Einzeilige Kommentare beginnen mit dem Hash-Zeichen ( # ) und enden am Zeilenende.

• Einzeiliger Kommentar:

# This is a single line comment in Python

• Inline-Kommentar:

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

• Kommentare, die sich über mehrere Zeilen erstrecken, haben an beiden Enden """ oder ''' . Dies ist mit einer mehrzeiligen Zeichenfolge identisch, sie können jedoch als Kommentar verwendet werden:

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

Programmgesteuerter Zugriff auf Docstrings

Docstrings werden - im Gegensatz zu regulären Kommentaren - als Attribut der von ihnen dokumentierten Funktion gespeichert, sodass Sie programmgesteuert darauf zugreifen können.

Eine Beispielfunktion

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

Die docstring kann mit dem zugegriffen werden __doc__ Attribut:

print(func.__doc__)

Dies ist eine Funktion, die überhaupt nichts bewirkt

help(func)

Hilfe zur Funktion func im Modul __main__ :

func()

Dies ist eine Funktion, die überhaupt nichts bewirkt

Eine weitere Beispielfunktion

function.__doc__ ist nur die eigentliche Dokumentzeichenfolge als Zeichenfolge, während die help allgemeine Informationen zu einer Funktion einschließlich der Dokumentzeichenfolge enthält. Hier ist ein hilfreicheres Beispiel:

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)

Hilfe zur Funktion greet in Modul __main__ :

greet(name, greeting='Hello')

Drucken einen Gruß an den Benutzer name
Optionale Parameterbegrüßung kann die greeting ändern.

Vorteile von Docstrings gegenüber regulären Kommentaren

Wenn Sie in einer Funktion keinen Dokumentstring oder einen regulären Kommentar eingeben, ist dies weniger hilfreich.

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__)

Keiner

help(greet)

Hilfe zur Funktionsbegrüßung im Modul main :

greet(name, greeting='Hello')

Schreiben Sie Dokumentation mit docstrings

Ein Dokumentstring ist ein mehrzeiliger Kommentar, der zum Dokumentieren von Modulen, Klassen, Funktionen und Methoden verwendet wird. Es muss die erste Aussage der Komponente sein, die es beschreibt.

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.
    """

Auf den Wert des Docstrings kann innerhalb des Programms zugegriffen werden und er wird beispielsweise vom Befehl help .

Syntaxkonventionen

PEP 257

PEP 257 definiert einen Syntaxstandard für Docstring-Kommentare. Es erlaubt grundsätzlich zwei Arten:

• Einzeilige Docstrings:

Gemäß PEP 257 sollten sie mit kurzen und einfachen Funktionen verwendet werden. Alles ist in einer Zeile angeordnet, zB:

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

Der docstring endet mit einem Punkt, das Verb sollte in der Imperativform sein.

• Mehrzeilige Docstrings:

Mehrzeilige Docstrings sollten für längere, komplexere Funktionen, Module oder Klassen verwendet werden.

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)

Sie beginnen mit einer kurzen Zusammenfassung (entspricht dem Inhalt eines einzeiligen Docstrings), die sich in derselben Zeile wie die Anführungszeichen oder in der nächsten Zeile befinden kann, und enthält zusätzliche Detail- und Listenparameter sowie Rückgabewerte.

Hinweis PEP 257 definiert, welche Informationen in einem Docstring angegeben werden sollen. Es definiert nicht, in welchem ​​Format es angegeben werden soll. Dies war der Grund dafür, dass andere Parteien und Dokumentations-Analysewerkzeuge ihre eigenen Standards für die Dokumentation festlegen, von denen einige unten und in dieser Frage aufgeführt sind .

Sphinx

Sphinx ist ein Tool zum Generieren von HTML-basierter Dokumentation für Python-Projekte auf der Grundlage von Dokumentstrings. Die verwendete Auszeichnungssprache ist reStructuredText . Sie definieren ihre eigenen Standards für die Dokumentation, pythonhosted.org bietet eine sehr gute Beschreibung dieser Standards. Das Sphinx-Format wird beispielsweise von der pyCharm-IDE verwendet .

Eine Funktion würde mit dem Format Sphinx / reStructuredText folgendermaßen dokumentiert:

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

Google Python Style Guide

Google hat den Google Python Style Guide veröffentlicht, in dem Kodierungskonventionen für Python definiert sind, einschließlich Dokumentationskommentare. Im Vergleich zur Sphinx / reST sagen viele Leute, dass die Dokumentation gemäß den Richtlinien von Google für Menschen besser lesbar ist.

Die oben erwähnte Seite pythonhosted.org enthält auch einige Beispiele für eine gute Dokumentation gemäß dem Google Style Guide.

Mit dem Napoleon- Plugin kann Sphinx auch Dokumentation im Google Style Guide-kompatiblen Format analysieren.

Eine Funktion würde im Google Style Guide-Format folgendermaßen dokumentiert:

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