Python Language
Opmerkingen en documentatie

Syntaxis

• # Dit is een opmerking van één regel
• print ("") # Dit is een inline reactie
• """
  Dit is
  een commentaar met meerdere regels
  """

Opmerkingen

Opmerkingen op één regel, inline en op meerdere regels

Opmerkingen worden gebruikt om code uit te leggen wanneer de basiscode zelf niet duidelijk is.

Python negeert opmerkingen en zal dus geen code uitvoeren of syntaxisfouten veroorzaken voor gewone Engelse zinnen.

Opmerkingen met één regel beginnen met het hekje ( # ) en worden beëindigd aan het einde van de regel.

• Enkele regel commentaar:

# This is a single line comment in Python

• Inline reactie:

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

• Opmerkingen die meerdere regels beslaan, hebben """ of ''' aan beide uiteinden. Dit is hetzelfde als een tekenreeks met meerdere regels, maar ze kunnen als opmerkingen worden gebruikt:

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

Programmatisch toegang tot docstrings

Docstrings worden - in tegenstelling tot reguliere opmerkingen - opgeslagen als een kenmerk van de functie die ze documenteren, wat betekent dat u ze programmatisch kunt openen.

Een voorbeeldfunctie

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

De docstring kan worden geopend met het kenmerk __doc__ :

print(func.__doc__)

Dit is een functie die helemaal niets doet

help(func)

Help op de functie func in module __main__ :

func()

Dit is een functie die helemaal niets doet

Nog een voorbeeldfunctie

function.__doc__ is gewoon de eigenlijke docstring als een string, terwijl de help algemene informatie geeft over een functie, inclusief de docstring. Hier is een nuttiger voorbeeld:

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)

Hulp bij functie greet in module __main__ :

greet(name, greeting='Hello')

Druk een groet aan de gebruiker name
Optionele parameter greeting kan veranderen wat ze begroet met.

Voordelen van docstrings ten opzichte van reguliere opmerkingen

Alleen het plaatsen van geen docstring of een gewone opmerking in een functie maakt het een stuk minder nuttig.

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

Geen

help(greet)

Help op de functie greet in module main:

greet(name, greeting='Hello')

Schrijf documentatie met behulp van docstrings

Een docstring is een commentaar met meerdere regels dat wordt gebruikt om modules, klassen, functies en methoden te documenteren. Het moet de eerste verklaring zijn van de component die het beschrijft.

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

De waarde van de docstring is toegankelijk binnen het programma en wordt bijvoorbeeld gebruikt door de help opdracht.

Syntaxisconventies

PEP 257

PEP 257 definieert een syntaxisstandaard voor docstring-opmerkingen. In principe zijn er twee soorten mogelijk:

• Eén regel Docstrings:

Volgens PEP 257 moeten ze worden gebruikt met korte en eenvoudige functies. Alles is op één regel geplaatst, bijvoorbeeld:

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

De docstring eindigt met een punt, het werkwoord moet de gebiedende wijs hebben.

• Multi-line Docstrings:

Multi-line docstring moet worden gebruikt voor langere, meer complexe functies, modules of klassen.

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)

Ze beginnen met een korte samenvatting (gelijk aan de inhoud van een docstring van één regel) die op dezelfde regel kan staan als de aanhalingstekens of op de volgende regel, geven extra detail- en lijstparameters en retourwaarden.

Opmerking PEP 257 definieert welke informatie binnen een docstring moet worden gegeven , het definieert niet in welk formaat deze moet worden gegeven. Dit was de reden voor andere partijen en tools voor het parseren van documentatie om hun eigen normen voor documentatie op te geven, waarvan sommige hieronder en in deze vraag worden vermeld.

Sfinx

Sphinx is een hulpmiddel om op HTML gebaseerde documentatie voor Python-projecten te genereren op basis van docstrings. De gebruikte opmaaktaal is reStructuredText . Ze definiëren hun eigen normen voor documentatie, pythonhosted.org biedt hier een zeer goede beschrijving van . Het Sphinx-formaat wordt bijvoorbeeld gebruikt door de pyCharm IDE .

Een functie zou op deze manier worden gedocumenteerd met de indeling 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 heeft de Google Python Style Guide gepubliceerd die coderingsconventies voor Python definieert, inclusief commentaar bij de documentatie. In vergelijking met de Sphinx / reST zeggen veel mensen dat documentatie volgens de richtlijnen van Google beter leesbaar is voor mensen.

De hierboven genoemde pagina pythonhosted.org biedt ook enkele voorbeelden voor goede documentatie volgens de Google Style Guide.

Met de Napoleon- plug-in kan Sphinx ook documentatie ontleden in de Google Style Guide-compatibele indeling.

Een functie zou als volgt worden gedocumenteerd in de Google Style Guide-indeling:

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