PEP8 – Programmare Python con stile

Introduzione

Python sta avendo sempre più successo come linguaggio di programmazione, anche al di fuori degli ambienti scientifici e accademici. Sempre più spesso troviamo del codice nativo scritto con questo linguaggio. Essendo un linguaggio abbastanza complesso è facile che ogni programmatore sviluppi un suo stile particolare, un modo di riportare un commento, di indentare una funzione e così via. Alla fine non ce ne rendiamo più conto e anche noi assumiamo uno stile tutto nostro…ma è corretto?

Lo standard PEP 8

Python è un linguaggio in via di sviluppo e molte nuove caratteristiche vengono inserite via via negli anni. Siamo arrivati alla versione 3.5 e molto è cambiato da quello che era il Python di 5 anni fa.

Tutte le caratteristiche del linguaggio vengono proposte, descritte e discusse in una serie di documenti ufficiali del linguaggio Python chiamati PEP (Python Enhancement Proposals). Ognuno di questi documenti ha un numero di riconoscimento e come titolo l’argomento discusso al suo interno. E’ possibile vedere l’elenco aggiornato di tutti i PEP pubblicati accedendo al PEP 0, ovvero all’indice di tutti i PEP.

Tra questi documenti ne esiste uno che ha il compito di raccogliere e riportare tutte le coding conventions per l’implementazione corretta e facilmente leggibile di un codice scritto in Python. Questo documento si chiama PEP 8 – Style guide per Python Code (vedi qui) e dal 2001 viene continuamente aggiornato in modo da essere una guida valida per tutti quelli che sviluppano codice con questo linguaggio. Tra gli autori di questo documento è presente Guido Van Rossum, l’ideatore del linguaggio Python.

La Coerenza come principio base

L’aspetto fondamentale che si deve tenere sempre in considerazione quando si scrive del codice è la coerenza. Questo aspetto è importantissimo quando si lavora all’interno di un progetto e si deve fare in modo che tutti quelli che vi prendono parte rispettino un certo stile.  PEP 8 ha lo scopo proprio di definire uno stile base da seguire.

Una nota interessante riportata nel documento ( “la sciocca coerenza è l’orco delle menti piccole” ) è che è un principio talmente forte che deve essere rispettato nonostante PEP8. Infatti se si dovesse aver a che fare con del codice esistente che non rispetta affatto alcuna regola di stile, la guida da seguire sarà quella definita dal progetto (se ne ha uno 😉 ) e non quella ufficiale descritta in PEP8 e valida per tutta la comunità Python.

Lunghezza massima delle righe

Molte periferiche sono limitate ad 80 caratteri. Quindi scrivendo righe contenenti un numero maggiori di 79 caratteri, porta molto spesso a vedere su schermo righe troncate dinamicamente, il che non facilità di certo la leggibilità del tutto. Si consiglia di sfruttare la sintassi del comando (per esempio una parentesi) per andare a capo mantenendo un buon livello di leggibilità. Se proprio non fosse possibile è possibile usare il carattere backslash ‘\’ per andare a capo.

Indentazione

Usare 4 spazi per i livelli di indentazione

if a > 2:
    print a

Inoltre quando si ha a che fare con comandi molto lunghi dove sono presenti parentesi di vario genere, si devono occupare più righe. Anche in questo caso dobbiamo riportare delle indentazioni (indentazioni interne), mantenendo il codice più leggibile possibile. Lo possiamo fare creando però delle indentazioni maggiori di 4 spazi, ciò per non confodersi con i comandi successivi.

def a_function_too_long_to_be_in_one_line(
       var_one, var two, var three,
       var_four):

    print(var_one)

Qui in questo caso, i parametri della funzione sono stati riportati con una indentazione di 6 spazi.

Righe vuote

Un buona prassi da seguire è quello di separare le definizioni di funzioni e di classi con due righe vuote. Inoltre è consigliabile lasciare una riga vuota anche prima della definizione di un metodo. Invece all’interno di una funzione o metodo, cercate di limitarne l’utilizzo il più possibile.

Utilizzare gli spazi nelle espressioni e nelle istruzioni

Un altro aspetto descritto in dettaglio all’interno della guida è l’uso che si deve fare degli spazi all’interno di comandi come espressioni o istruzioni di assegnazione. Le regole indicate sono semplici da capire e seguire.

Non utilizzare gli spazi immediatamente prima o dopo le parentesi o prima della punteggiatura

sum( array[ 2 ] , { value: 2 ] )        NO

andrebbe scritta nel seguente modo:

sum(array[2], {value: 2})               SI

in cui gli spazi vengono lasciati solo dopo la punteggiatura come virgole e due punti.

Nelle espressioni deve essere presente un solo spazio prima e dopo l’operatore.

x                = 1                NO
x=x-1

andrebbe scritta

x = 1                              SI 
x = x - 1

attenzione però a non confondere il segno = dell’assegnazione che richiede gli spazi, con il caso in cui = viene usato per indicare un argomento di una funzione con un valore di default.

Il segno = nelle dichiarazioni di valori default degli argomenti di una funzione non vogliono spazi.

def function(var1, var2 = 0.0):            NO

andrebbe scritta

def function(var1, var2=0.0)               SI

Commenti

Per prima cosa, indipendentemente da come si scrivono, i commenti hanno un ruolo importantissimo per la leggibilità del codice. Quindi devono essere sempre presenti ed aggiornati!

Dato che si tratta di un testo scritto, è buona prassi, scrivere il primo carattere con la lettera maiuscola a meno che non si riporti un riferimento ad una variabile nel codice.

Prima di definire una classe o un metodo, o un modulo, si utilizzano dei commenti descrittivi piuttosto lunghi che occupano diverse righe. Questi commenti vengono chiamati commenti a blocco e vanno indentati correttamente.  Ogni riga di questo genere di commenti inizia con un segno # seguito da uno spazio. I paragrafi del commento invece devono essere separati da righe vuote che comunque iniziano con un segno #.

# This is a class which defines a sample. The sample has two
# lists of double values.
#
# Use this comment when you need to describe the functionalities and
# feature of the following class or function.

Inoltre, vicino a particolari comandi o espressioni, o assegnazioni di variabili, si inseriscono commenti brevi, indicativi, chiamati commenti in linea. Questi brevi commenti dovrebbero contenere pochi caratteri ed essere separati dall’istruzione da almeno due spazi vuoti.

 x = function(y)   # getting a result

Questi commenti possono essere utilissimi se messi al posto giusto e ridotti all’essenziale. Non abbondate e non scrivete l’ovvio, altrimenti la leggibilità del testo andrà via via diminuendo.

Convenzioni sui nomi

Forse il punto più dolente e meno rispettato quando si deve scrivere del codice in Python, è proprio la convenzione dei nomi.

I nomi dei moduli possono essere tutti in minuscolo oppure avere delle iniziali maiuscolo. Per esempio MyModule o mymodule sono entrambe utilizzate. Generalmente i moduli che contengono solamente funzioni hanno nomi completamente in minuscolo. Comunque, quando si ha a che fare con dei veri e propri pacchetti, allora il nome dovrebbe essere tutto minuscolo.

I nomi delle Classi hanno le iniziali maiuscole, tipo MyClass.

I nomi delle funzioni, possono espresse in tutti i modi, o con le maiuscole iniziali tipo MyFunction, o tutte minuscole, tipo myfunction, o anche con le sottolineature per indicare gli spazi, come my_function. Per quanto riguarda i metodi, le regole sono pressochè le stesse delle funzioni. Solo che per i metodi interni e per variabili di istanza sarebbe preferibile aggiungere un carattere di sottolineatura all’inizio del nome. Questo evita eventuali conflitti di nome che si potrebbero generare. Mentre è d’obbligo utilizzare due sottolineature per gli attributi e le funzioni a cui solo la classe corrente possa accedere.

Conclusioni

Questo breve articolo può essere molto utile per chi programma in Python. Spesso è facile dimenticare qualche regola e non c’è da meravigliarsi se ogni tanto qualcuno di noi va a ridare un’occhiata a queste regole. Inoltre Python è forse il linguaggio di programmazione più utilizzato nell’Open Source. Quindi spetta a tutti noi renderlo il più coerente e leggibile possibile.