Python Language
Commenti e documentazione

Sintassi

• # Questo è un commento a riga singola
• print ("") # Questo è un commento in linea
• """
  Questo è
  un commento su più righe
  """

Osservazioni

Commenti a riga singola, in linea e multilinea

I commenti sono usati per spiegare il codice quando il codice di base non è chiaro.

Python ignora i commenti, quindi non eseguirà il codice, o creerà errori di sintassi per semplici frasi inglesi.

I commenti a riga singola iniziano con il carattere hash ( # ) e terminano alla fine della riga.

• Commento a riga singola:

# This is a single line comment in Python

• Commento in linea:

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

• I commenti che si estendono su più righe hanno """ o ''' su entrambe le estremità. È lo stesso di una stringa multilinea, ma possono essere utilizzati come commenti:

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

Accesso programmatico alle docstring

Le docstring sono, a differenza dei normali commenti, memorizzate come attributo della funzione che documentano, il che significa che è possibile accedervi a livello di programmazione.

Una funzione di esempio

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

È possibile accedere alla docstring utilizzando l'attributo __doc__ :

print(func.__doc__)

Questa è una funzione che non fa nulla

help(func)

Aiuto sulla funzione func nel modulo __main__ :

func()

Questa è una funzione che non fa nulla

Un'altra funzione di esempio

function.__doc__ è solo la docstring effettiva come una stringa, mentre la funzione help fornisce informazioni generali su una funzione, inclusa la docstring. Ecco un esempio più utile:

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)

Aiuto sulla funzione greet nel modulo __main__ :

greet(name, greeting='Hello')

Stampa un saluto al name utente
Il greeting facoltativo dei parametri può modificare ciò con cui vengono salutati.

Vantaggi delle docstring rispetto ai commenti regolari

Non è sufficiente inserire alcuna docstring o un commento regolare in una funzione.

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

Nessuna

help(greet)

Aiuto sulla funzione di benvenuto nel modulo principale :

greet(name, greeting='Hello')

Scrivi la documentazione usando le docstring

Una docstring è un commento su più righe usato per documentare moduli, classi, funzioni e metodi. Deve essere la prima affermazione del componente che descrive.

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

È possibile accedere al valore di docstring all'interno del programma ed è, ad esempio, utilizzato dal comando help .

Convenzioni sulla sintassi

PEP 257

PEP 257 definisce uno standard di sintassi per i commenti di docstring. In pratica consente due tipi:

• Docstrings a una riga:

Secondo PEP 257, dovrebbero essere utilizzati con funzioni brevi e semplici. Tutto è posto in una riga, ad esempio:

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

La docstring terminerà con un periodo, il verbo dovrebbe essere nella forma imperativa.

• Docstrings multilinea:

La docintazione su più righe dovrebbe essere utilizzata per funzioni, moduli o classi più lunghi e complessi.

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)

Iniziano con un breve sommario (equivalente al contenuto di una docstring su una riga) che può trovarsi sulla stessa riga delle virgolette o sulla riga successiva, fornire ulteriori dettagli e parametri di lista e valori di ritorno.

Nota PEP 257 definisce quali informazioni dovrebbero essere fornite all'interno di una docstring, non definisce in quale formato deve essere fornita. Questo è stato il motivo per cui le altre parti e gli strumenti di analisi della documentazione hanno specificato i propri standard per la documentazione, alcuni dei quali sono elencati di seguito e in questa domanda .

Sfinge

Sfinge è uno strumento per generare documentazione basata su HTML per progetti Python basati su docstring. Il suo linguaggio di markup usato è reStructuredText . Definiscono i propri standard per la documentazione, pythonhosted.org ospita una descrizione molto buona di loro . Il formato Sfinge è ad esempio utilizzato da pyCharm IDE .

Una funzione sarebbe documentata in questo modo usando il formato 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 Style Guide di Google

Google ha pubblicato Google Python Style Guide che definisce le convenzioni di codifica per Python, inclusi i commenti alla documentazione. In confronto alla Sfinge / REST molte persone dicono che la documentazione secondo le linee guida di Google è meglio leggibile.

La pagina pythonhosted.org menzionata sopra fornisce anche alcuni esempi di buona documentazione secondo la Google Style Guide.

Usando il plugin Napoleon , Sphinx può anche analizzare la documentazione nel formato conforme alla Guida dello stile di Google.

Una funzione sarebbe documentata in questo modo utilizzando il formato della Guida di stile di 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