6: La documentazione

6: LA DOCUMENTAZIONE

IL PROBLEMA DELLA DOCUMENTAZIONE

Il numero delle funzioni definite nei vari modulli di Python è enorme, e continua ad aumentare ad ogni nuova versione del linguaggio. Come sapete ogni modulo raggruppa funzioni e costanti attinenti tra loro (ad esempio funzioni matematiche, per le stringhe, per gestire il tempo e la data, ecc).

Ma per usare queste funzioni bisogna ricordare, per ognuna di esse, il numero di parametri da indicare nella chiamata, il valore restituito, le eventuali eccezioni che essa può provocare ... insomma, anche un esperto programmatore non potrà mai ricordare tutte queste cose a memoria, e dovrà spesso consultare della documentazione che gli ricordi velocemente i parametri di ogni funzione. Per questo esistono vari siti che danno le cosiddette reference, cioè degli elenchi dettagliati di ogni funzione del linguaggio con la relativa spiegazione del suo comportamento.

I programmatori di Python hanno deciso di avere un approccio diverso a questo problema, cioè quello di includere la documentazione nel linguaggio stesso. Proviamo ad esempio ad importare in IDLE un modulo: scrivendo

help(nome_modulo)

ci apparirà una lunga stringa che spiega per prima cosa il nome del modulo e poi elenca una per una tutte le funzioni contenute con una spiegazione di quello che fa ogni funzione e del significato dei suoi parametri. Questo è un esempio (ho riportato solo le prime righe, l'intera stringa è lunghissima):


>>> import time
>>> help(time)

	
Help on built-in module time:

NAME
    time - This module provides various functions to manipulate time values.

DESCRIPTION
    There are two standard representations of time.  One is the number
    of seconds since the Epoch, in UTC (a.k.a. GMT).  It may be an integer
    or a floating point number (to represent fractions of seconds).
    The Epoch is system-defined; on Unix, it is generally January 1st, 1970.
    The actual value can be retrieved by calling gmtime(0).     

    .   .   .

Scrivendo invece

help(nome_funzione)

(solo il nome della funzione, senza le parentesi che servono nella chiamata) otterremo una stringa più breve con gli argomenti della sola funzione. Ad esempio:


>>> help(time.sleep)

	      
Help on built-in function sleep in module time:

sleep(...)
    sleep(seconds)
    
    Delay execution for a given number of seconds.  The argument may be
    a floating point number for subsecond precision.

Immaginiamo ora di essere un programmatore professionista e di scrivere una serie di funzioni che dovranno poi essere usate da altri. Anche noi abbiamo bisogno di documentare il nostro codice, altrimenti le persone che useranno le nostre funzioni dovranno rivolgersi continuamente a noi per ogni chiarimento. Ma un programmatore Python si aspetta di poter ricevere aiuto su una qualsiasi funzione semplicemente scrivendo help(nome_funzione). Come possiamo fare?

LE DOCSTRINGS

Per documentare una funzione Python sfrutta abilmente il fatto che un'istruzione che contenga solamente una costante (senza nessuna operazione o assegnazione) è perfettamente lecita ma non ha alcun effetto. Ad esempio, in un programma potremmo inserire, in una posizione qualsiasi, delle linee di codice come queste:


100000000
"Ciao"

(ovviamente indentate correttamente): questo codice non avrebbe nessun effetto sul programma, ma non provocherebbe alcun errore.

Una docstring è una stringa (eventualmente su più linee) scritta come prima istruzione in un modulo, nella definizione di una funzione o di una classe. Questa stringa verrà mostrata da Python scrivendo help(nome_funzione). Definiamo, come esempio, una semplice funzione in IDLE (quando premete INVIO dopo la prima riga Python comprende che la definizione continua nelle righe successive: aggiustate l'indentazione e continuate, premete INVIO su una riga vuota per terminare la definizione):


>>> def double(num):
	"""Returns the double of num"""
	return num * 2
	
	
>>>

Ora chiediamo aiuto sulla funzione appena definita, e vediamo che IDLE ci risponde con la docstring che abbiamo inserito:

				    
>>> help(double)
				    
	
Help on function double in module __main__:

double(num)
    Returns the double of num

Se programmate per hobby probabilmente non avrete mai bisogno di scrivere docstring, ma questo diventa una necessità (insieme alle opportune regole di "etichetta" che vedremo nel prossimo paragrafo) se volete far conoscere il vostro lavoro alla comunità dei programmatori, in quanto nessuno sarebbe disposto a spaccarsi la testa per capire cosa fa il vostro codice, e quindi verreste considerati poco professionali. Naturalmente anche scrivere in Inglese è indispensabile!

CONVENZIONI

I programmatori Python si sono dati alcune regole che cercano di standardizzare la scrittura delle docstrings. Per gli esperti questo è il documento ufficiale cui fare riferimento PEP 257 -- Docstring Conventions, qui farò solo un breve riassunto su come commentare funzioni e moduli

Le docstrings dovrebbero sempre essere scritte tra triple virgolette """Stringa""", allo scopo di essere immediatamente riconoscibili come tali;
In casi molto semplici una docstring può occupare una sola riga (di max 72 caratteri per leggibilità), con una concisa descrizione di quello che descrive;
```
"""This is a very simple docstring"""
```
Altrimenti la docstring dovrebbe svilupparsi su più righe, ed avere questo formato: una prima riga di descrizione concisa, poi una riga vuota e poi la descrizione dettagliata. Questa suddivisione (in Inglese brief/detailed) è adottata da molti programmi che generano automaticamente la documentazione, usando le brief per compilare un indice di link che rimandano ai rispettivi detailed e quindi porterebbe questi programmi a confondersi se non adottata;
```
"""This is the brief description

This is the detailed description, which explains all you want to know.
It can span many
many,
many lines of code"""
```
Tutte le righe di una docstring multilinea dovrebbero essere indentate allo stesso livello delle tre virgolette iniziali. Alcuni usano (ma non è obbligatorio) chiudere la docsring con una riga vuota e le virgolette nella riga successiva
```
def func():
    """This is the brief description

    This is the detailed description, which explains all you want to know.
    It can span many
    many,
    many lines of code"""
```
Nelle descrizioni non bisogna cominciare includendo il soggetto (ad esempio "This function ...") ma partire direttamente con il verbo. Nella descrizione di una funzione dovrebbero essere riportati i significati (e i tipi) dei suoi parametri, il valore restituito e le eventuali eccezioni sollevate dalla funzione.

CREIAMO UN MODULO DI PROVA

Come esercizio finale creiamo un nostro modulo documentandolo con le docstrings. Aprite l'editor di file e scrivete queste linee di codice:


"""This is a sample module showing how docstrings work

It contains two documented functions and nothing else.
This was done for didactic purposes"""


def double(num):
    """Returns the double of num"""

    return 2 * num


def hypotenuse(s1, s2):
    """Returns the hypotenuse of a right triangle

    s1, s2 are the other two sides of the triangle.
    It uses the Pythagorean theorem"""

    return (s1 ** 2 + s2 ** 2) ** 0.5

Salvate il file come sampledoc.py, poi provate ad importarlo da IDLE, chiamando la help()con il nome del modulo e con quello delle varie funzioni.


>>> import sampledoc
			    
>>> help(sampledoc)
 
	
Help on module sampledoc:

NAME
    sampledoc - This is a sample module showing how docstrings work

DESCRIPTION
    It contains two documented functions and nothing else.
    This was done for didactic purposes

FUNCTIONS
    double(num)
        Returns the double of num
    
    hypotenuse(s1, s2)
        Returns the hypotenuse of a right triangle
        
        s1, s2 are the other two sides of the triangle.
        It uses the Pythagorean theorem

FILE
    c:\users\nicola\python\sampledoc.py

Fine della lezione