Come documentare il codice Python

Se stai iniziando con Python e vuoi saperne di più, segui il corso Intermediate Python di DataCamp.

Perché è importante documentare il tuo progetto

La documentazione è una parte essenziale di qualsiasi progetto su cui lavori, indipendentemente dal linguaggio di programmazione che usi. Un progetto con varie API attive e utilizzate da molti utenti ma privo di documentazione sarebbe considerato incompleto. Per un attimo, immaginati come sviluppatore: come ti sentiresti se volessi replicare un progetto o usare una parte di un progetto che non ha alcuna documentazione? Probabilmente avresti difficoltà a integrarlo nella tua architettura.

Una documentazione migliore renderà il tuo progetto più riuscito, perché quando condividi il progetto o il software con il mondo, vorresti che venisse usato; questo vale soprattutto per i progetti open source, dove l'obiettivo è ancora più ambizioso. Vorresti anche che la community contribuisse al tuo progetto e lo migliorasse.

Il celebre autore del linguaggio Python afferma che il codice viene letto più spesso di quanto venga scritto. Questa citazione mette in evidenza l'importanza che la documentazione ha sul tuo codice o progetto quando viene implementato da altri.

Immagina di lavorare per l'azienda XYZ, sei nel periodo di preavviso e il tuo manager vuole che tu trasferisca quel progetto a un collega. Potresti fargli una KT (knowledge transfer), ma cosa succede se il tuo collega non riesce a eseguire correttamente uno dei codici del progetto? Le ragioni potrebbero essere diverse: ad esempio, i binari su cui gira il tuo codice potrebbero non corrispondere a quelli dell'attuale sistema operativo.

Che cos'è esattamente una documentazione?

La documentazione ha diversi componenti. Deve essere ben strutturata attorno a questi elementi e rispettarli per essere considerata una documentazione appropriata.

A un livello astratto, i componenti sono:

• Assicurarsi che il codice del progetto sia ben commentato.

• Seguire gli standard di codifica PEP 8 di Python.

• Tutorial concreti su come è stato costruito il progetto, soprattutto quando si tratta di un progetto open source sviluppato con finalità didattiche.

• Una guida su come installare i pacchetti e i moduli necessari per costruire il software, e una scheda tecnica se il progetto include anche dell'hardware. Ad esempio, come installare Anaconda, TensorFlow, Keras, ecc.

• Diverse discussioni sull'avanzamento del progetto a ogni step che possano aver portato alla realizzazione del software.

• Materiale di riferimento che fornisce una descrizione tecnica dello stack tecnologico utilizzato in fase di sviluppo.

• Il design architetturale del progetto o della soluzione software.

Questi punti sono solo alcuni dei componenti che potrebbero esistere in una documentazione ben strutturata e completa. È importante mantenere distinti tutti questi elementi: renderà anche più semplice mantenere la documentazione in futuro.

Un esempio di documentazione completa che include la maggior parte dei componenti discussi potrebbe essere simile a quella mostrata di seguito:

Molte persone confondono spesso commentare e documentare e li considerano simili. I commenti descrivono il codice all'utente, al manutentore e anche a te stesso come riferimento futuro. Funzionano solo a livello di codice e possono essere considerati un sottoinsieme della documentazione. I commenti aiutano a:

• capire il tuo codice,
• renderlo autoesplicativo e
• comprenderne scopo e design.

È importante ricordare che, poiché Python segue gli standard di codifica PEP 8, anche i commenti devono rispettare tali standard. La documentazione ufficiale di Python afferma che, per blocchi di testo lunghi con poche restrizioni strutturali (docstring o commenti), la lunghezza delle righe dovrebbe essere limitata a 72 caratteri.

Per verificare se il tuo codice aderisce agli standard PEP 8, puoi usare il modulo Python pylint. Questo modulo può essere usato per modificare il limite di caratteri per i commenti e per tutte le altre righe di codice.

Vediamo un paio di esempi.

• Descrizione di import di un modulo

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.

• Descrizione della definizione di variabile

n_classes = 10 # MNIST total classes (0-9 digits)

Per approfondire il tema dei commenti e delle buone pratiche, dai un'occhiata a questo post utile.

Vediamo ora come le docstring possono aiutare a documentare il codice del tuo progetto.

Docstring per documentare il codice Python

La Docstring in Python è una stringa di documentazione letterale che compare nella definizione di classe, modulo, funzione o metodo e viene scritta come prima istruzione. Le docstring sono accessibili tramite l'attributo di documentazione (__doc__) di qualsiasi oggetto Python e possono essere consultate anche con la funzione built-in help().

Le docstring sono ottime per capire la funzionalità delle parti più ampie del codice, cioè lo scopo generale di una classe, di un modulo o di una funzione. I commenti, invece, vengono usati per il codice, le istruzioni e le espressioni e tendono a essere brevi. Sono un testo descrittivo scritto da un programmatore principalmente per sé stesso, per sapere cosa fa una riga di codice o un'espressione, e anche per chi desidera contribuire a quel progetto. Documentare il codice è una parte essenziale per scrivere codice pulito e programmi ben strutturati. Anche se già accennato, non esistono regole rigide per farlo.

Esistono due forme di docstring: docstring su una sola riga e docstring su più righe. Sono la documentazione comunemente usata da data scientist e programmatori nei loro progetti.

• Le docstring one-line sono docstring che stanno tutte su una riga. Puoi usare uno dei tipi di virgolette, cioè triple apici singoli o tripli doppi apici; l'apertura e la chiusura devono essere dello stesso tipo. Nelle docstring su una riga, le virgolette di chiusura stanno sulla stessa riga di quelle di apertura. La convenzione più comune è usare i tripli doppi apici.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.

• Le docstring multi-line contengono la stessa riga di stringa iniziale delle one-line docstring, ma sono seguite da una riga vuota e da testo descrittivo.

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Dalla tabella sopra, scegliamo Pydoc come uno dei formati di docstring ed esploriamolo un po'.

Come hai visto, le docstring sono accessibili tramite l'attributo Python __doc__ e la funzione help(). Puoi anche usare il modulo integrato Pydoc, molto diverso per funzionalità rispetto all'attributo doc e alla funzione help.

Pydoc è uno strumento utile quando vuoi condividere il codice con i colleghi o renderlo open source, caso in cui ti rivolgi a un pubblico più ampio. Può generare pagine web dalla tua documentazione Python e può anche avviare un server web.

Vediamo come funziona.

Il modo più semplice e comodo per eseguire il modulo Pydoc è lanciarlo come script. Per eseguirlo all'interno di una cella di Jupyter Lab, userai il punto esclamativo (!).

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Se guardi l'output sopra, il primo utilizzo di Pydoc è mostrare la documentazione testuale di una funzione, di un modulo, di una classe, ecc. Vediamo quindi come puoi sfruttarlo meglio rispetto alla funzione help.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Ora estraiamo la documentazione di glob usando la funzione help.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Come vedi, viene generato un NameError perché glob non è definito. Per usare help e ottenere la documentazione, devi prima importare quel modulo, mentre con Pydoc non è necessario.

Esploriamo ora la funzione più interessante del modulo Pydoc, cioè l'esecuzione di Pydoc come servizio web.

Per farlo, esegui semplicemente Pydoc come script con l'argomento -b, che avvia un server HTTP su una porta libera a caso e apre un browser per navigare interattivamente nella documentazione. Questo è utile soprattutto quando hai vari altri servizi in esecuzione sul sistema e non ricordi quale porta sia libera.

!python -m pydoc -b

^C

Nel momento in cui esegui la cella sopra, si aprirà una nuova finestra su una porta casuale e il browser apparirà simile a quello mostrato di seguito.

Vediamo la documentazione del modulo h5py, un formato di file usato per memorizzare i pesi delle architetture di reti neurali.

Elementi essenziali per documentare progetti Python

Indipendentemente da obiettivi, visione e scopo, la documentazione di ogni progetto è più o meno la stessa. Il progetto potrebbe rientrare nelle seguenti categorie:

• Progetto privato (personale): può servire per costruire il portfolio o per lavorare come freelancer mantenendo un repository GitHub.

• Progetti collaborativi (di team): può essere un progetto nella tua organizzazione o un lavoro per una competizione Kaggle.

• Progetti open source: sono pensati soprattutto per essere condivisi con un pubblico ampio. Si aspettano collaborazione, contributi e mantenibilità del codice e della documentazione nel lungo periodo.

Anche se queste tre categorie di progetti hanno visioni diverse, il template di documentazione può essere condiviso tra tutti i tipi di progetto.

Mettiamo che tu stia lavorando a un progetto open source e debba creare un repository GitHub con documentazione dettagliata e aggiornata regolarmente: ecco i punti essenziali da tenere a mente:

• File dei requisiti: spesso gli autori se ne dimenticano, ma è molto importante. Aiuta gli utenti a riprodurre rapidamente il tuo codice. Di solito è un file di testo che contiene tutti i pacchetti e i moduli, con le rispettive versioni, usati nel progetto. I requisiti possono anche essere menzionati nel file Readme, ma averli separati è sempre meglio, perché l'utente può semplicemente eseguire quel file con un comando pip e tutte le dipendenze verranno installate sul suo sistema.

• Readme: il file Readme è solitamente in formato markdown e funge anche da spina dorsale per molti progetti. Un riepilogo del progetto, le sue funzionalità e il suo scopo con un bel logo. Dovrebbe includere istruzioni per installare o utilizzare il progetto. In più, aggiungi eventuali modifiche significative dalla versione precedente. Script di test o una guida rapida per eseguire con successo il codice direttamente nel Readme danno più fiducia all'utente nel seguire il tuo progetto. Può anche evidenziare i potenziali problemi che gli utenti potrebbero incontrare.

• Come collaborare: è importante, soprattutto nei progetti open source. Dovrebbe includere come i nuovi collaboratori possono contribuire al progetto: sviluppare nuove funzionalità, correggere bug noti, aggiungere documentazione, aggiungere nuovi test o segnalare problemi. I collaboratori potrebbero persino rilasciare una versione 2.0 dello stesso progetto e portarlo a un livello superiore.

• Licenza: un file di testo in chiaro che descrive la licenza usata dal tuo progetto. Particolarmente cruciale per i progetti open source: licenze come Boost, Apache, MIT, ecc. Informano l'utente se il progetto è libero di essere usato commercialmente e fino a che punto.

• Assegnazione dei task: se lavori su un progetto condiviso come Kaggle, puoi definire i task assegnati a ciascun membro e il livello di avanzamento. Questo aiuta a tenere traccia dei progressi complessivi del progetto.

• Riutilizzabilità del framework: è fondamentale in un progetto condiviso come Kaggle, dove i compagni di team possono riutilizzare ciò che hai costruito, risparmiando molto tempo. Ad esempio, pipeline di preprocessing dei dati, script di cross-validation, ecc.

Una documentazione altamente consigliata, molto ben strutturata e che potrebbe essere un perfetto esempio di come dovrebbe apparire un progetto open source è il repository GitHub dei transformer di huggingface.

Conclusione

Congratulazioni per aver terminato il tutorial.

Un buon esercizio per tutti è esplorare un po' di più il modulo Pydoc e altri formati di docstring di Python come Epydoc e Google docstrings per capire in cosa differiscono.

Per qualsiasi domanda relativa a questo tutorial, scrivi pure nella sezione commenti qui sotto.

Riferimenti:

• Docstring in Python

Se stai iniziando con Python e vuoi saperne di più, segui il corso Intermediate Python di DataCamp.