Python Language
Kommentarer och dokumentation

Syntax

• # Det här är en kommentar på en rad
• print ("") # Detta är en inline kommentar
• """
  Detta är
  en kommentar med flera linjer
  """

Anmärkningar

Enkel rad, inline och multiline kommentarer

Kommentarer används för att förklara koden när själva grundkoden inte är tydlig.

Python ignorerar kommentarer, och kommer därför inte att köra kod där inne eller höja syntaxfel för vanliga engelska meningar.

Kommentarer på en rad börjar med hashkaraktären ( # ) och avslutas i slutet av raden.

• Kommentar med en rad:

# This is a single line comment in Python

• Inline kommentar:

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

• Kommentarer som spänner över flera rader har """ eller ''' båda ändarna. Detta är samma som en flersträngssträng, men de kan användas som kommentarer:

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

Programmatisk åtkomst till dokument

Dokumentationer lagras - till skillnad från vanliga kommentarer - som ett attribut för den funktion de dokumenterar, vilket innebär att du kan komma åt dem programmatiskt.

En exempelfunktion

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

Du kan __doc__ attributet __doc__ :

print(func.__doc__)

Detta är en funktion som inte gör någonting alls

help(func)

Hjälp på funktions func i modul __main__ :

func()

Detta är en funktion som inte gör någonting alls

Ett annat exempel på funktionen

function.__doc__ är bara själva docstring som en sträng, medan help funktionen ger allmän information om funktion, inklusive docstring. Här är ett mer användbart exempel:

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)

Hjälp på funktions greet i modul __main__ :

greet(name, greeting='Hello')

Skriv en hälsning till användaren name
Valfri parameter greeting kan ändra vad de möts med.

Fördelar med dokumentation över regelbundna kommentarer

Bara att sätta någon dokstring eller en vanlig kommentar i en funktion gör det mycket mindre användbart.

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

Ingen

help(greet)

Hjälp för funktionshälsa i modulens huvud :

greet(name, greeting='Hello')

Skriv dokumentation med hjälp av dokument

En dokstring är en kommentar på flera linjer som används för att dokumentera moduler, klasser, funktioner och metoder. Det måste vara det första uttalandet för den komponent som den beskriver.

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

Värdet på docstring kan nås inom programmet och är - till exempel - som används av help kommando.

Syntaxkonventioner

PEP 257

PEP 257 definierar en syntaxstandard för att kommentera kommentarer. Det tillåter i princip två typer:

• Enlinjedokumentationer:

Enligt PEP 257 bör de användas med korta och enkla funktioner. Allt placeras i en rad, t.ex.

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

Doksträngen ska avslutas med en period, verbet ska vara i den nödvändiga formen.

• Flerstreckade dokument:

Flerstreckad docstring bör användas för längre, mer komplexa funktioner, moduler eller klasser.

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)

De börjar med en kort sammanfattning (motsvarande innehållet i en en-radig dokstring) som kan vara på samma rad som citattecknen eller på nästa rad, ge ytterligare detaljer och lista parametrar och returvärden.

Obs PEP 257 definierar vilken information som ska ges i en dokumentsträng, den definierar inte i vilket format den ska ges. Detta var orsaken till att andra parter och analysverktyg för dokumentation specificerade sina egna standarder för dokumentation, av vilka några är listade nedan och i denna fråga .

Sfinx

Sphinx är ett verktyg för att generera HTML-baserad dokumentation för Python-projekt baserat på docstrings. Dess markeringsspråk som används är reStructuredText . De definierar sina egna standarder för dokumentation, pythonhosted.org är en mycket bra beskrivning av dem . Sphinx-formatet används till exempel av pyCharm IDE .

En funktion skulle dokumenteras så här med formatet 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

Google Python Style Guide

Google har publicerat Google Python Style Guide som definierar kodningskonventioner för Python, inklusive dokumentationskommentarer. I jämförelse med Sphinx / reST säger många att dokumentation enligt Googles riktlinjer är bättre läsbar för människor.

Sidan pythonhosted.org som nämns ovan ger också några exempel för god dokumentation enligt Google Style Guide.

Med Napoleon- insticksprogrammet kan Sphinx också analysera dokumentation i Google Style Guide-kompatibelt format.

En funktion skulle dokumenteras på detta sätt med formatet Google Style Guide:

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